File

File library provides useful tools to traverse through folders, check files and paths for safety, and generate folder structures based on creation time and/or id.

folder_check()

Cleans a path and makes sure that it is jailed to my project folder basepath. This can take full paths (within the basepath) or relatives to the basepath.

string $path The path of the file either relative to the basepath, or a full path within the basepath.
string $custom_error The error message to fail on if an incorrect path is found.
boolean $add_trailing_slash If this is a folder, then the trailing slash is added after sanitization. Defaults to true.
boolean $fatal_error If this is a true, fatal error will stop execution on failure. Defaults to true.
@return string|boolean Returns the sanitized path relative to the basepath if successful. Fatal error if not. If parameter $fatal_error was set to false, then boolean false is returned for invalid path.

file_check()

Same as folder_check() except that this does not add a trailing slash by default (since it is for files).

string $path The path of the file either relative to the basepath, or a full path within the basepath.
string $custom_error The error message to fail on if an incorrect path is found.
boolean $fatal_error If this is a true, fatal error will stop execution on failure. Defaults to true.
@return string|boolean Returns the sanitized file path relative to the basepath if successful. Fatal error if not.

sanitize()

Sanitize a file name by removing all special characters.

string $filename The original file name.
@return string The sanitized file name.

get_relative_path()

Given an absolute path it will return the relative path.

string $absolute_path The absolute path to a file or folder.
@return string|boolean The relative path to the file or folder or false if failed.

get_files_in_dir()

Returns an array of files found in this folder.

string $path The absolute path to check for files.
boolean $recursive If set to true, subfolders will also be checked. False by default.
string $mode Can be ‘files’ or ‘folders’. This should not be used. If you want to check for folders, use {@link get_folders_in_dir()} instead.
boolean $hidden_files_and_folders If set to true, hidden files and folders (beginning with .) will also be included. False by default.
@return array An array of file paths within the directory.

get_files()

Same as get_files_in_dir() but path argument is relative to basepath. Returns an array of files found in this folder.

string $path The path to check for files relative to the apps basepath.
boolean $recursive If set to true, subfolders will also be checked. False by default.
string $mode Can be ‘files’ or ‘folders’. This should not be used. If you want to check for folders, use {@link get_folders_in_dir()} instead.
boolean $hidden_files_and_folders If set to true, hidden files and folders (beginning with .) will also be included. False by default.
@return array An array of absolute file paths within the directory.

get_folders_in_dir()

Returns an array of folders found in this folder. If set to recursive, the folder paths will be returned relative to the specified path.

string $path The path to check for folders.
boolean $recursive If set to true, subfolders will also be checked. False by default.
boolean $hidden_files_and_folders If set to true, hidden files and folders (beginning with .) will also be included. False by default.
@return array An array of folder paths within the directory.

get_folders()

Same as get_folders_in_dir(), but relative to basepath. Returns an array of folders found in this folder. If set to recursive, the folder paths will be returned relative to the specified path.

string $path The path to check for folders.
boolean $recursive If set to true, subfolders will also be checked. False by default.
boolean $hidden_files_and_folders If set to true, hidden files and folders (beginning with .) will also be included. False by default.
@return array An array of absolute folder paths within the directory.

get_extension()

Returns the extension section of the file.

string $filename The full filename, including extension.
@return string The file’s extension

create_path_for()

Creates folders and subfolders for the specified file name.

string $filename The full filename, including extension.
@return bool

is_correct_extension()

Checks if the extension is valid.

string $filename The full filename, including extension.
array|string $extORextarray A single extension (string) or an array of extensions (array of strings). Defaults to an array of image extensions (jpg, jpeg, png, gif)
@return boolean True if the file extension is valid according to the specified list.

get_time_path()

Generate a hierarchy of subfolders based on the timestamp. So for example: 2010/Jan/3/example.txt could be created.

string $basepath The base path of the file (this will not use the global base path!)
string $filename The full filename, including extension.
integer $timestamp The UNIX time stamp to use for generating the folders. The current timestamp will be used by default.
boolean $create_folders_if_they_dont_exist If set to true, the folders will not only be calculated, but also created.
bool $include_day Whether to include the day level as well.
@return string The new full path of the file.

get_id_path()

Generate a hierarchy of subfolders based on the file name. So example.txt at $level 3 will generate a path of e/x/a/example.txt

string $basepath The base path of the file (this will not use the global base path!)
string $filename The full filename, including extension.
boolean $create_folders_if_they_dont_exist If set to true, the folders will not only be calculated, but also created.
integer $level The number of levels of subfolders to calculate with.
@return string The new full path of the file.

get_mime_type()

Get mime-type of file based on the extension. This is not too reliable, since it takes the file name and not file content as the key.

string $filename The full filename, including extension.
string|boolean $file_path The relative file path to the project base path. This is optional. It will be used to check the actual file as well if the mime based on extension fails.
@return string The mime type of the file

download()

IMPORTANT! This is potentially dangerous! Be sure to sanitize any user input!

Download a file specified by relative path. There are some checks here, but be careful to sanitize the input as this is a potentially dangerous function.

string $file_path The relative file path to the project base path.
string|boolean $download_name If specified, the file will download with this name.
string|boolean $mime_type The mime type for the file. If not given, it will try to detect it automatically.
@return boolean|array There is no return value and execution stop here because the file is returned. Tests return an array.

download_time()

Calculate download time (in seconds).

integer $bytes The file size in bytes.
integer $kbps The connection speed in Kbps (kiloBITS per second!)
@return integer The time in seconds

file_size_format()

Format the value like a ‘human-readable’ file size (i.e. ’13 KB’, ‘4.1 MB’, ‘102 bytes’, etc).

integer $bytes The number of bytes.
@return string A human-readable string of file size.