File
Reference for the File module: every function with its full signature, parameters and return type. Read, write and append files, read byte ranges and sizes, and create, copy, list, empty and remove directories, with each path checked before use.
This page is a pure reference. For how the framework fits together, see the Guide.
File- static functions for reading, writing and appending files and managing directories.
File
The main class: static functions for file and directory operations, listed alphabetically. Paths are checked before use.
Append
File::Append($filename, $data, $create_file)
Append data to the end of a file. When the file does not exist, it is created only if creation is requested.
| Name | Type | Description |
|---|---|---|
$filename | | The file to append to. |
$data | | The string data to append. |
$create_file | | When true, create the file if it is missing; when false, do nothing if it is missing. |
Returns bool True when the full data was written.
CopyDir
File::CopyDir($src, $dst, $skip_checks = false)
Recursively copy a source directory into a destination. The destination may be a single path or an array of paths, in which case the tree is copied into each.
| Name | Type | Description |
|---|---|---|
$src | | The source directory. |
$dst | | The destination directory, or an array of destination directories. |
$skip_checks | | When true, skip the path and readability checks (used on recursion). |
Returns void
EmptyDir
File::EmptyDir($dir, $yes_i_want_to_delete_all_files)
Recursively delete every file and subdirectory inside a directory. The confirmation flag must be true for anything to be deleted.
| Name | Type | Description |
|---|---|---|
$dir | | The directory to empty. |
$yes_i_want_to_delete_all_files | | Must be true to confirm the deletion. |
Returns void
Exists
File::Exists($file)
Whether the given file or directory exists.
| Name | Type | Description |
|---|---|---|
$file | | The path to test. |
Returns bool True when the path exists.
GetBytes
File::GetBytes($filename, $start, $length)
Read a run of bytes from a file, starting at an offset. Returns the empty string when the length is not positive or the read fails.
| Name | Type | Description |
|---|---|---|
$filename | | The file to read from. |
$start | | The byte offset to start reading at. |
$length | | The number of bytes to read. |
Returns string The bytes read, or the empty string.
GetFiles
File::GetFiles(string $path)
The names of the files directly inside a directory, excluding subdirectories and the dot entries.
| Name | Type | Description |
|---|---|---|
$path | string | The directory to list. |
Returns array A list of file names.
GetSize
File::GetSize($file)
The size of a file in bytes.
| Name | Type | Description |
|---|---|---|
$file | | The file to measure. |
Returns int The file size in bytes.
GetSubDirs
File::GetSubDirs($path)
The subdirectories directly inside a directory, as full paths.
| Name | Type | Description |
|---|---|---|
$path | | The directory to list. |
Returns array A list of subdirectory paths.
Glob
File::Glob($basedir, $filepattern = '*', $recursive = false, $full_path = true)
Match files under a base directory against a glob pattern. When not recursive, paths are returned relative to the base directory; when recursive, the full path form is chosen by the flag.
| Name | Type | Description |
|---|---|---|
$basedir | | The directory to search under. |
$filepattern | | The glob pattern to match; brace patterns are supported. |
$recursive | | When true, descend into subdirectories. |
$full_path | | When recursive, whether to return full paths rather than paths relative to the base directory. |
Returns array A list of matching file paths.
IsDirEmpty
File::IsDirEmpty($dir)
Whether a directory contains no entries beyond the dot entries.
| Name | Type | Description |
|---|---|---|
$dir | | The directory to test. |
Returns bool True when the directory is empty.
MakeDir
File::MakeDir($name, $cached = false)
Create a directory when it does not already exist. When caching is on, a successful creation is remembered so repeat calls for the same path return immediately.
| Name | Type | Description |
|---|---|---|
$name | | The directory path to create. |
$cached | | When true, cache successful creations for this path. |
Returns bool True when the directory was created, or was cached as created.
Read
File::Read($filename, $default = null, $cache = false)
Read the contents of a file into a string. Returns null when the file is missing or unreadable, and the given default when an error is thrown. When caching is on, the contents are remembered for repeat reads.
| Name | Type | Description |
|---|---|---|
$filename | | The file to read. |
$default | | The value returned when a read error is thrown. |
$cache | | When true, cache and reuse the contents for this file. |
Returns string|null The file contents, or null, or the default.
RemoveDirIfEmpty
File::RemoveDirIfEmpty($name)
Remove a directory only when it is empty.
| Name | Type | Description |
|---|---|---|
$name | | The directory to remove. |
Returns bool True when the directory was removed.
RemoveFile
File::RemoveFile($name)
Delete a file when it exists.
| Name | Type | Description |
|---|---|---|
$name | | The file to delete. |
Returns bool True when the file was deleted.
Write
File::Write($filename, &$data, $replace = false)
Write data to a file. An existing file is overwritten only when replacement is requested.
| Name | Type | Description |
|---|---|---|
$filename | | The file to write. |
$data | | The data to write, passed by reference. |
$replace | | When true, overwrite an existing file; when false, do not write if it already exists. |
Returns int|bool The number of bytes written, or false when nothing was written.