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.

csv_headers()

This method can be used to return a simple column map for CSV headers. By default it will return an array containing all headers and their positions, but if provided an array of specific headers, only those will be returned.

Arguments

Type	Description	Default
string	CSV file path.
array	Header(s) to find. See below for more information.	All columns.
string	Delimiter.	","

Returns

If successful, an associative array is returned using the header values as keys, column positions as values. FALSE is returned on failure.

If an array containing specific headers is passed, only those values are returned. These headers may be specified as either a simple array (e.g. ["one", "two"]) or an associative array keyed with nicer labels (e.g. ["email"=>"some_stupid_long_header"]). In cases of the latter, the nice key ("email") will be used for the return value rather than the true cell value.

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')?>" />

dirsize()

Recursively count up all the bytes of all the files under a given directory.

Be careful pointing this at very large directories; the number of operations can quickly add up. :)

Arguments

Type	Description
string	Directory path.

Returns

This function always returns an integer representing the cumulative byte size. If a directory is invalid or empty, 0 is returned.

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);

line_count()

Count the number of lines in a text file as efficiently as possible.

Arguments

Type	Description	Default
string	File path.
bool	Ignore empty lines or lines consisting only of whitespace.	TRUE

Returns

This method returns an integer representing the number of lines. If a file is invalid or empty, 0 is returned.

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.