Page MenuHomePhorge

final class Filesystem
libphutil Technical Documentation (Filesystem)

Simple wrapper class for common filesystem tasks like reading and writing files. When things go wrong, this class throws detailed exceptions with good information about what didn't work.

Filesystem will resolve relative paths against PWD from the environment. When Filesystem is unable to complete an operation, it throws a FilesystemException.

Tasks

Directories

  • public static function createDirectory($path, $umask, $recursive) — Create a directory in a manner similar to mkdir(), but throw detailed exceptions on failure.
  • public static function createTemporaryDirectory($prefix, $umask, $root_directory) — Create a temporary directory and return the path to it. You are responsible for removing it (e.g., with Filesystem::remove()) when you are done with it.
  • public static function listDirectory($path, $include_hidden) — List files in a directory.
  • public static function walkToRoot($path, $root) — Return all directories between a path and the specified root directory (defaulting to "/"). Iterating over them walks from the path to the root.

Files

  • public static function readFile($path) — Read a file in a manner similar to file_get_contents(), but throw detailed exceptions on failure.
  • public static function writeFile($path, $data) — Write a file in a manner similar to file_put_contents(), but throw detailed exceptions on failure. If the file already exists, it will be overwritten.
  • public static function writeUniqueFile($base, $data) — Write data to unique file, without overwriting existing files. This is useful if you want to write a ".bak" file or something similar, but want to make sure you don't overwrite something already on disk.
  • public static function appendFile($path, $data) — Append to a file without having to deal with file handles, with detailed exceptions on failure.
  • public static function copyFile($from, $to) — Copy a file, preserving file attributes (if relevant for the OS).
  • public static function remove($path) — Remove a file or directory.
  • public static function rename($old, $new) — Rename a file or directory.
  • private static function executeRemovePath($path) — Internal. Recursively remove a file or an entire directory. Implements the core function of @{method:remove} in a way that works on Windows.
  • public static function changePermissions($path, $umask) — Change the permissions of a file or directory.
  • public static function getModifiedTime($path) — Get the last modified time of a file
  • public static function readRandomBytes($number_of_bytes) — Read random bytes from /dev/urandom or equivalent. See also @{method:readRandomCharacters}.
  • public static function readRandomCharacters($number_of_characters) — Read random alphanumeric characters from /dev/urandom or equivalent. This method operates like @{method:readRandomBytes} but produces alphanumeric output (a-z, 0-9) so it's appropriate for use in URIs and other contexts where it needs to be human readable.
  • public static function getMimeType($path, $default) — Identify the MIME type of a file. This returns only the MIME type (like text/plain), not the encoding (like charset=utf-8).

Paths

  • public static function resolvePath($path, $relative_to) — Canonicalize a path by resolving it relative to some directory (by default PWD), following parent symlinks and removing artifacts. If the path is itself a symlink it is left unresolved.
  • public static function isDescendant($path, $root) — Test whether a path is descendant from some root path after resolving all symlinks and removing artifacts. Both paths must exists for the relation to obtain. A path is always a descendant of itself as long as it exists.
  • public static function readablePath($path, $pwd) — Convert a canonical path to its most human-readable format. It is guaranteed that you can use resolvePath() to restore a path to its canonical format.
  • public static function pathExists($path) — Determine whether or not a path exists in the filesystem. This differs from file_exists() in that it returns true for symlinks. This method does not attempt to resolve paths before testing them.
  • public static function pathsAreEquivalent($u, $v) — Determine if two paths are equivalent by resolving symlinks. This is different from resolving both paths and comparing them because resolvePath() only resolves symlinks in parent directories, not the path itself.

Executables

  • public static function binaryExists($binary) — Determine if an executable binary (like `git` or `svn`) exists within the configured `$PATH`.
  • public static function resolveBinary($binary) — Locates the full path that an executable binary (like `git` or `svn`) is at the configured `$PATH`.

Assertions

  • public static function assertExists($path) — Assert that something (e.g., a file, directory, or symlink) exists at a specified location.
  • public static function assertNotExists($path) — Assert that nothing exists at a specified location.
  • public static function assertIsFile($path) — Assert that a path represents a file, strictly (i.e., not a directory).
  • public static function assertIsDirectory($path) — Assert that a path represents a directory, strictly (i.e., not a file).
  • public static function assertWritable($path) — Assert that a file or directory exists and is writable.
  • public static function assertReadable($path) — Assert that a file or directory exists and is readable.

Other Methods

  • public function __get($name)
  • public function __set($name, $value)
  • public function current()
  • public function key()
  • public function next()
  • public function rewind()
  • public function valid()
  • private function throwOnAttemptedIteration()
  • public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.
  • public static function assertWritableFile($path) — Make assertions about the state of path in preparation for writeFile() and writeFileIfChanged().
  • public static function writeFileIfChanged($path, $data) — Write a file in a manner similar to `file_put_contents()`, but only touch the file if the contents are different, and throw detailed exceptions on failure.
  • public static function readRandomInteger($min, $max) — Generate a random integer value in a given range.
  • public static function isAbsolutePath($path) — Checks if a path is specified as an absolute path.
  • public static function concatenatePaths($components)

Methods

public function __get($name)
Inherited

This method is not documented.
Parameters
$name
Return
wild

public function __set($name, $value)
Inherited

This method is not documented.
Parameters
$name
$value
Return
wild

public function current()
Inherited

This method is not documented.
Return
wild

public function key()
Inherited

This method is not documented.
Return
wild

public function next()
Inherited

This method is not documented.
Return
wild

public function rewind()
Inherited

This method is not documented.
Return
wild

public function valid()
Inherited

This method is not documented.
Return
wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.
Return
wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters
string$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue of the constant.

public static function readFile($path)

Read a file in a manner similar to file_get_contents(), but throw detailed exceptions on failure.

Parameters
string$pathFile path to read. This file must exist and be readable, or an exception will be thrown.
Return
stringContents of the specified file.

public static function assertWritableFile($path)

Make assertions about the state of path in preparation for writeFile() and writeFileIfChanged().

Parameters
$path
Return
wild

public static function writeFile($path, $data)

Write a file in a manner similar to file_put_contents(), but throw detailed exceptions on failure. If the file already exists, it will be overwritten.

Parameters
string$pathFile path to write. This file must be writable and its parent directory must exist.
string$dataData to write.
Return
wild

public static function writeFileIfChanged($path, $data)

Write a file in a manner similar to file_put_contents(), but only touch the file if the contents are different, and throw detailed exceptions on failure.

As this function is used in build steps to update code, if we write a new file, we do so by writing to a temporary file and moving it into place. This allows a concurrently reading process to see a consistent view of the file without needing locking; any given read of the file is guaranteed to be self-consistent and not see partial file contents.

Parameters
string$pathfile path to write
string$datadata to write
Return
booleanindicating whether the file was changed by this function.

public static function writeUniqueFile($base, $data)

Write data to unique file, without overwriting existing files. This is useful if you want to write a ".bak" file or something similar, but want to make sure you don't overwrite something already on disk.

This function will add a number to the filename if the base name already exists, e.g. "example.bak", "example.bak.1", "example.bak.2", etc. (Don't rely on this exact behavior, of course.)

Parameters
string$baseSuggested filename, like "example.bak". This name will be used if it does not exist, or some similar name will be chosen if it does.
string$dataData to write to the file.
Return
stringPath to a newly created and written file which did not previously exist, like "example.bak.3".

public static function appendFile($path, $data)

Append to a file without having to deal with file handles, with detailed exceptions on failure.

Parameters
string$pathFile path to write. This file must be writable or its parent directory must exist and be writable.
string$dataData to write.
Return
wild

public static function copyFile($from, $to)

Copy a file, preserving file attributes (if relevant for the OS).

Parameters
string$fromFile path to copy from. This file must exist and be readable, or an exception will be thrown.
string$toFile path to copy to. If a file exists at this path already, it wll be overwritten.
Return
wild

public static function remove($path)

Remove a file or directory.

Parameters
string$pathFile to a path or directory to remove.
Return
void

public static function rename($old, $new)

Rename a file or directory.

Parameters
string$oldOld path.
string$newNew path.
Return
wild

private static function executeRemovePath($path)

Internal. Recursively remove a file or an entire directory. Implements the core function of remove() in a way that works on Windows.

Parameters
string$pathFile to a path or directory to remove.
Return
void

public static function changePermissions($path, $umask)

Change the permissions of a file or directory.

Parameters
string$pathPath to the file or directory.
int$umaskPermission umask. Note that umask is in octal, so you should specify it as, e.g., `0777', not `777'.
Return
void

public static function getModifiedTime($path)

Get the last modified time of a file

Parameters
string$pathPath to file
Return
intTime last modified

public static function readRandomBytes($number_of_bytes)

Read random bytes from /dev/urandom or equivalent. See also readRandomCharacters().

Parameters
int$number_of_bytesNumber of bytes to read.
Return
stringRandom bytestring of the provided length.

public static function readRandomCharacters($number_of_characters)

Read random alphanumeric characters from /dev/urandom or equivalent. This method operates like readRandomBytes() but produces alphanumeric output (a-z, 0-9) so it's appropriate for use in URIs and other contexts where it needs to be human readable.

Parameters
int$number_of_charactersNumber of characters to read.
Return
stringRandom character string of the provided length.

public static function readRandomInteger($min, $max)

Generate a random integer value in a given range.

This method uses less-entropic random sources under older versions of PHP.

Parameters
int$minMinimum value, inclusive.
int$maxMaximum value, inclusive.
Return
wild

public static function getMimeType($path, $default)

Identify the MIME type of a file. This returns only the MIME type (like text/plain), not the encoding (like charset=utf-8).

Parameters
string$pathPath to the file to examine.
string$defaultOptional default mime type to return if the file's mime type can not be identified.
Return
stringFile mime type.

public static function createDirectory($path, $umask, $recursive)

Create a directory in a manner similar to mkdir(), but throw detailed exceptions on failure.

Parameters
string$pathPath to directory. The parent directory must exist and be writable.
int$umaskPermission umask. Note that umask is in octal, so you should specify it as, e.g., `0777', not `777'.
boolean$recursiveRecursively create directories. Default to false.
Return
stringPath to the created directory.

public static function createTemporaryDirectory($prefix, $umask, $root_directory)

Create a temporary directory and return the path to it. You are responsible for removing it (e.g., with Filesystem::remove()) when you are done with it.

Parameters
string$prefixOptional directory prefix.
int$umaskPermissions to create the directory with. By default, these permissions are very restrictive (0700).
string$root_directoryOptional root directory. If not provided, the system temporary directory (often "/tmp") will be used.
Return
stringPath to newly created temporary directory.

public static function listDirectory($path, $include_hidden)

List files in a directory.

Parameters
string$pathPath, absolute or relative to PWD.
bool$include_hiddenIf false, exclude files beginning with a ".".
Return
arrayList of files and directories in the specified directory, excluding `.' and `..'.

public static function walkToRoot($path, $root)

Return all directories between a path and the specified root directory (defaulting to "/"). Iterating over them walks from the path to the root.

Parameters
string$pathPath, absolute or relative to PWD.
string$rootThe root directory.
Return
list<string>List of parent paths, including the provided path.

public static function isAbsolutePath($path)

Checks if a path is specified as an absolute path.

Parameters
string$path
Return
bool

public static function resolvePath($path, $relative_to)

Canonicalize a path by resolving it relative to some directory (by default PWD), following parent symlinks and removing artifacts. If the path is itself a symlink it is left unresolved.

Parameters
string$pathPath, absolute or relative to PWD.
$relative_to
Return
stringCanonical, absolute path.

public static function isDescendant($path, $root)

Test whether a path is descendant from some root path after resolving all symlinks and removing artifacts. Both paths must exists for the relation to obtain. A path is always a descendant of itself as long as it exists.

Parameters
string$pathChild path, absolute or relative to PWD.
string$rootRoot path, absolute or relative to PWD.
Return
boolTrue if resolved child path is in fact a descendant of resolved root path and both exist.

public static function readablePath($path, $pwd)

Convert a canonical path to its most human-readable format. It is guaranteed that you can use resolvePath() to restore a path to its canonical format.

Parameters
string$pathPath, absolute or relative to PWD.
string$pwdOptionally, working directory to make files readable relative to.
Return
stringHuman-readable path.

public static function pathExists($path)

Determine whether or not a path exists in the filesystem. This differs from file_exists() in that it returns true for symlinks. This method does not attempt to resolve paths before testing them.

Parameters
string$pathTest for the existence of this path.
Return
boolTrue if the path exists in the filesystem.

public static function binaryExists($binary)

Determine if an executable binary (like git or svn) exists within the configured $PATH.

Parameters
string$binaryBinary name, like `'git'` or `'svn'`.
Return
boolTrue if the binary exists and is executable.

public static function resolveBinary($binary)

Locates the full path that an executable binary (like git or svn) is at the configured $PATH.

Parameters
string$binaryBinary name, like `'git'` or `'svn'`.
Return
stringThe full binary path if it is present, or null.

public static function pathsAreEquivalent($u, $v)

Determine if two paths are equivalent by resolving symlinks. This is different from resolving both paths and comparing them because resolvePath() only resolves symlinks in parent directories, not the path itself.

Parameters
string$uFirst path to test for equivalence.
string$vSecond path to test for equivalence.
Return
boolTrue if both paths are equivalent, i.e. reference the same entity in the filesystem.

public static function concatenatePaths($components)

This method is not documented.
Parameters
array$components
Return
wild

public static function assertExists($path)

Assert that something (e.g., a file, directory, or symlink) exists at a specified location.

Parameters
string$pathAssert that this path exists.
Return
void

public static function assertNotExists($path)

Assert that nothing exists at a specified location.

Parameters
string$pathAssert that this path does not exist.
Return
void

public static function assertIsFile($path)

Assert that a path represents a file, strictly (i.e., not a directory).

Parameters
string$pathAssert that this path is a file.
Return
void

public static function assertIsDirectory($path)

Assert that a path represents a directory, strictly (i.e., not a file).

Parameters
string$pathAssert that this path is a directory.
Return
void

public static function assertWritable($path)

Assert that a file or directory exists and is writable.

Parameters
string$pathAssert that this path is writable.
Return
void

public static function assertReadable($path)

Assert that a file or directory exists and is readable.

Parameters
string$pathAssert that this path is readable.
Return
void