Files and Paths

Why are filesystems such a bitch? Haha. This class contains functions to help with filesystem tasks and path manipulation.

Use:
\blobfolio\common\file (by value)
\blobfolio\common\ref\file (by reference)

copy()

Recursively copy files and/or directories, attempting to preserve file permissions too.

Arguments

Type	Description
string	Source path.
string	Destination path.

Returns

Returns TRUE if the last copy operation succeeded, FALSE otherwise.

data_uri()

Return a file as a Data-URI for, e.g., embedding in HTML.

Arguments

Type	Description
string	File path.

Returns

Returns a Data-URI string on success or FALSE if the file could not be opened.

Example

<img src="<?=\blobfolio\common\file::data_uri('/path/to/world.jpg')?>" />

empty_dir()

Determine whether a directory is empty.

Arguments

Type	Description
string	File path.

Returns

Returns TRUE if the directory is empty, FALSE if it isn't or if the path was unreadable.

hash_dir()

This function will recursively hash all files within a directory, and return a hash of that result. This can be used to e.g. detect deep content changes.

Note: The file hashing component can be resource-intensive. Be careful combining heavy algorithms with large directories. See here for supported algorithms.

Arguments

Type	Description	Default
string	Directory path.
string	Algorithm to use for the final result.	MD5
string	Algorithm to use for individual files.	Same as result.

Returns

If either the directory or result hashing algorithm are invalid, FALSE is returned. If a directory is empty, a hash of the string "empty" is returned. Otherwise a hash of all file hashes is returned.

leadingslash()

Ensure the path has a leading "/".

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes
string, array	File path.	If an array is passed, each value will be processed recursively.

Returns

Returns the path with a leading "/" if passed by value, otherwise TRUE.

Example

// By value.
$foo = \blobfolio\common\file::leadingslash('hello'); // /hello

// By reference.
\blobfolio\common\ref\file::leadingslash($foo);

mkdir()

Recursively make a directory. While the native PHP mkdir() function has a recursive option, for some reason it does not consistently apply the desired permissions to all new nested directories.

Arguments

Type	Description	Default
string	Directory path.
mixed	Octal permissions like 0755.	If not specified, the class' base directory permissions will be used.

Returns

Returns TRUE if the directories were created (or already existed), otherwise FALSE.

path()

Convert backslashes to forwardslashes, end directories with a trailing slash, expand symlinks, and resolve to absolute paths (when possible).

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes	Default
string, array	File path.	If an array is passed, each value will be processed recursively.
bool	Validate path.	If TRUE, the path must exist and be readable.	TRUE

Returns

Returns the sanitized path if passed by value. If validating and the path is bad, FALSE is returned. When passed by value, TRUE or FALSE is returned.

Example

// By value.
$foo = \blobfolio\common\file::path('..\hello'); // /var/www/foobar/hello/
$foo = \blobfolio\common\file::path('../hello', true); // FALSE

// By reference.
\blobfolio\common\ref\file::path($foo);

readfile_chunked()

This buffers the contents of a file in chunks, greatly reducing the strain on a web server when transmitting large files through PHP.

Arguments

Type	Description	Notes	Default
string	File path.
bool	Return bytes.	When TRUE, the function returns the number of bytes like readfile(), otherwise the status is returned.	TRUE

Returns

The contents of the file are buffered and flushed. The function returns either the byte count or status of the read.

redirect()

Unset $_REQUEST data (if any) and issue a redirect to another location. By default this will be accomplished by sending a "Location" header, but if headers have already been sent it will output Javascript instead.

Arguments

Type	Description
string	URL.

Returns

N/A

rmdir()

Recursively remove a directory.

Arguments

Type	Description
string	Directory path.

Returns

Returns TRUE if the directory was removed, FALSE if there was any sort of problem.

scandir()

Recursively build a list of directories and/or files under a given path. Unlike PHP's native scandir(), . and .. paths are never included.

Arguments

Type	Description	Default
string	Directory path.
bool	Include files.	TRUE
bool	Include directories.	TRUE
int	Max depth.	-1 (infinite)

Returns

This method always returns an array.

trailingslash()

Ensure a path ends in a "/".

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes
string, array	File path.	If an array is passed, each value will be processed recursively.

Returns

Returns the slashed path if passed by value, otherwise TRUE.

unixslash()

Convert "\" to "/" and fix a few stupid things along the way.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes
string, array	File path.	If an array is passed, each value will be processed recursively.

Returns

Returns the slashed path if passed by value, otherwise TRUE.

unleadingslash()

Remove the leading slash on a path, if any.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes
string, array	File path.	If an array is passed, each value will be processed recursively.

Returns

Returns the unslashed path if passed by value, otherwise TRUE.

unparse_url()

The opposite of parse_url(), this will rebuild a URL given an array of parts.

Note: like parse_url(), this doesn't imply the result is actually a valid URL.

Arguments

Type	Description	Notes
array	URL parts.	The structure should match output from parse_url().

Returns

Returns a URL as a string or FALSE if invalid.

Example

$parsed = parse_url('https://google.com?s=Foobar');
/*
Array
(
    [scheme] => https
    [host] => google.com
    [query] => s=Foobar
)
*/
echo \blobfolio\common\file::unparse_url($parsed); // https://google.com?s=Foobar

untrailingslash()

Remove the tailing slash from a path, if any.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes
string, array	File path.	If an array is passed, each value will be processed recursively.

Returns

Returns the unslashed path if passed by value, otherwise TRUE.