Mercurial > hg > isophonics-drupal-site
view core/lib/Drupal/Core/File/FileSystemInterface.php @ 18:af1871eacc83
Update to Drupal core 8.7.1
author | Chris Cannam |
---|---|
date | Thu, 09 May 2019 15:33:08 +0100 |
parents | 4c8ae668cc8c |
children |
line wrap: on
line source
<?php namespace Drupal\Core\File; /** * Provides an interface for helpers that operate on files and stream wrappers. */ interface FileSystemInterface { /** * Flag for dealing with existing files: Appends number until name is unique. */ const EXISTS_RENAME = 0; /** * Flag for dealing with existing files: Replace the existing file. */ const EXISTS_REPLACE = 1; /** * Flag for dealing with existing files: Do nothing and return FALSE. */ const EXISTS_ERROR = 2; /** * Flag used by ::prepareDirectory() -- create directory if not present. */ const CREATE_DIRECTORY = 1; /** * Flag used by ::prepareDirectory() -- file permissions may be changed. */ const MODIFY_PERMISSIONS = 2; /** * Moves an uploaded file to a new location. * * PHP's move_uploaded_file() does not properly support streams if * open_basedir is enabled, so this function fills that gap. * * Compatibility: normal paths and stream wrappers. * * @param string $filename * The filename of the uploaded file. * @param string $uri * A string containing the destination URI of the file. * * @return bool * TRUE on success, or FALSE on failure. * * @see move_uploaded_file() * @see https://www.drupal.org/node/515192 * @ingroup php_wrappers */ public function moveUploadedFile($filename, $uri); /** * Sets the permissions on a file or directory. * * This function will use the file_chmod_directory and * file_chmod_file settings for the default modes for directories * and uploaded/generated files. By default these will give everyone read * access so that users accessing the files with a user account without the * webserver group (e.g. via FTP) can read these files, and give group write * permissions so webserver group members (e.g. a vhost account) can alter * files uploaded and owned by the webserver. * * PHP's chmod does not support stream wrappers so we use our wrapper * implementation which interfaces with chmod() by default. Contrib wrappers * may override this behavior in their implementations as needed. * * @param string $uri * A string containing a URI file, or directory path. * @param int $mode * Integer value for the permissions. Consult PHP chmod() documentation for * more information. * * @return bool * TRUE for success, FALSE in the event of an error. * * @ingroup php_wrappers */ public function chmod($uri, $mode = NULL); /** * Deletes a file. * * PHP's unlink() is broken on Windows, as it can fail to remove a file when * it has a read-only flag set. * * @param string $uri * A URI or pathname. * @param resource $context * Refer to http://php.net/manual/ref.stream.php * * @return bool * Boolean TRUE on success, or FALSE on failure. * * @see unlink() * @ingroup php_wrappers */ public function unlink($uri, $context = NULL); /** * Resolves the absolute filepath of a local URI or filepath. * * The use of this method is discouraged, because it does not work for * remote URIs. Except in rare cases, URIs should not be manually resolved. * * Only use this function if you know that the stream wrapper in the URI uses * the local file system, and you need to pass an absolute path to a function * that is incompatible with stream URIs. * * @param string $uri * A stream wrapper URI or a filepath, possibly including one or more * symbolic links. * * @return string|false * The absolute local filepath (with no symbolic links) or FALSE on failure. * * @see \Drupal\Core\StreamWrapper\StreamWrapperInterface::realpath() * @see http://php.net/manual/function.realpath.php * @ingroup php_wrappers */ public function realpath($uri); /** * Gets the name of the directory from a given path. * * PHP's dirname() does not properly pass streams, so this function fills that * gap. It is backwards compatible with normal paths and will use PHP's * dirname() as a fallback. * * Compatibility: normal paths and stream wrappers. * * @param string $uri * A URI or path. * * @return string * A string containing the directory name. * * @see dirname() * @see https://www.drupal.org/node/515192 * @ingroup php_wrappers */ public function dirname($uri); /** * Gets the filename from a given path. * * PHP's basename() does not properly support streams or filenames beginning * with a non-US-ASCII character. * * @see http://bugs.php.net/bug.php?id=37738 * @see basename() * * @ingroup php_wrappers */ public function basename($uri, $suffix = NULL); /** * Creates a directory, optionally creating missing components in the path to * the directory. * * When PHP's mkdir() creates a directory, the requested mode is affected by * the process's umask. This function overrides the umask and sets the mode * explicitly for all directory components created. * * @param string $uri * A URI or pathname. * @param int $mode * Mode given to created directories. Defaults to the directory mode * configured in the Drupal installation. It must have a leading zero. * @param bool $recursive * Create directories recursively, defaults to FALSE. Cannot work with a * mode which denies writing or execution to the owner of the process. * @param resource $context * Refer to http://php.net/manual/ref.stream.php * * @return bool * Boolean TRUE on success, or FALSE on failure. * * @see mkdir() * @see https://www.drupal.org/node/515192 * @ingroup php_wrappers * * @todo Update with open_basedir compatible recursion logic from * \Drupal\Component\PhpStorage\FileStorage::ensureDirectory(). */ public function mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL); /** * Removes a directory. * * PHP's rmdir() is broken on Windows, as it can fail to remove a directory * when it has a read-only flag set. * * @param string $uri * A URI or pathname. * @param resource $context * Refer to http://php.net/manual/ref.stream.php * * @return bool * Boolean TRUE on success, or FALSE on failure. * * @see rmdir() * @ingroup php_wrappers */ public function rmdir($uri, $context = NULL); /** * Creates a file with a unique filename in the specified directory. * * PHP's tempnam() does not return a URI like we want. This function will * return a URI if given a URI, or it will return a filepath if given a * filepath. * * Compatibility: normal paths and stream wrappers. * * @param string $directory * The directory where the temporary filename will be created. * @param string $prefix * The prefix of the generated temporary filename. * Note: Windows uses only the first three characters of prefix. * * @return string|bool * The new temporary filename, or FALSE on failure. * * @see tempnam() * @see https://www.drupal.org/node/515192 * @ingroup php_wrappers */ public function tempnam($directory, $prefix); /** * Returns the scheme of a URI (e.g. a stream). * * @param string $uri * A stream, referenced as "scheme://target" or "data:target". * * @return string|bool * A string containing the name of the scheme, or FALSE if none. For * example, the URI "public://example.txt" would return "public". * * @see file_uri_target() */ public function uriScheme($uri); /** * Checks that the scheme of a stream URI is valid. * * Confirms that there is a registered stream handler for the provided scheme * and that it is callable. This is useful if you want to confirm a valid * scheme without creating a new instance of the registered handler. * * @param string $scheme * A URI scheme, a stream is referenced as "scheme://target". * * @return bool * Returns TRUE if the string is the name of a validated stream, or FALSE if * the scheme does not have a registered handler. */ public function validScheme($scheme); /** * Copies a file to a new location without invoking the file API. * * This is a powerful function that in many ways performs like an advanced * version of copy(). * - Checks if $source and $destination are valid and readable/writable. * - If file already exists in $destination either the call will error out, * replace the file or rename the file based on the $replace parameter. * - If the $source and $destination are equal, the behavior depends on the * $replace parameter. FILE_EXISTS_REPLACE will error out. * FILE_EXISTS_RENAME will rename the file until the $destination is unique. * - Provides a fallback using realpaths if the move fails using stream * wrappers. This can occur because PHP's copy() function does not properly * support streams if open_basedir is enabled. See * https://bugs.php.net/bug.php?id=60456 * * @param string $source * A string specifying the filepath or URI of the source file. * @param string $destination * A URI containing the destination that $source should be copied to. The * URI may be a bare filepath (without a scheme). * @param int $replace * Replace behavior when the destination file already exists: * - FileManagerInterface::FILE_EXISTS_REPLACE - Replace the existing file. * - FileManagerInterface::FILE_EXISTS_RENAME - Append _{incrementing * number} until the filename is unique. * - FileManagerInterface::FILE_EXISTS_ERROR - Throw an exception. * * @return string * The path to the new file. * * @throws \Drupal\Core\File\Exception\FileException * Implementation may throw FileException or its subtype on failure. */ public function copy($source, $destination, $replace = self::EXISTS_RENAME); /** * Deletes a file without database changes or hook invocations. * * This function should be used when the file to be deleted does not have an * entry recorded in the files table. * * @param string $path * A string containing a file path or (streamwrapper) URI. * * @throws \Drupal\Core\File\Exception\FileException * Implementation may throw FileException or its subtype on failure. */ public function delete($path); /** * Deletes all files and directories in the specified filepath recursively. * * If the specified path is a directory then the function is called * recursively to process the contents. Once the contents have been removed * the directory is also removed. * * If the specified path is a file then it will be processed with delete() * method. * * Note that this only deletes visible files with write permission. * * @param string $path * A string containing either an URI or a file or directory path. * @param callable|null $callback * Callback function to run on each file prior to deleting it and on each * directory prior to traversing it. For example, can be used to modify * permissions. * * @throws \Drupal\Core\File\Exception\FileException * Implementation may throw FileException or its subtype on failure. */ public function deleteRecursive($path, callable $callback = NULL); /** * Moves a file to a new location without database changes or hook invocation. * * This is a powerful function that in many ways performs like an advanced * version of rename(). * - Checks if $source and $destination are valid and readable/writable. * - Checks that $source is not equal to $destination; if they are an error * is reported. * - If file already exists in $destination either the call will error out, * replace the file or rename the file based on the $replace parameter. * - Works around a PHP bug where rename() does not properly support streams * if safe_mode or open_basedir are enabled. * * @param string $source * A string specifying the filepath or URI of the source file. * @param string $destination * A URI containing the destination that $source should be moved to. The * URI may be a bare filepath (without a scheme) and in that case the * default scheme (public://) will be used. * @param int $replace * Replace behavior when the destination file already exists: * - FILE_EXISTS_REPLACE - Replace the existing file. * - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename * is unique. * - FILE_EXISTS_ERROR - Do nothing and return FALSE. * * @return string * The path to the new file. * * @throws \Drupal\Core\File\Exception\FileException * Implementation may throw FileException or its subtype on failure. * * @see https://bugs.php.net/bug.php?id=60456 */ public function move($source, $destination, $replace = self::EXISTS_RENAME); /** * Saves a file to the specified destination without invoking file API. * * This function is identical to file_save_data() except the file will not be * saved to the {file_managed} table and none of the file_* hooks will be * called. * * @param string $data * A string containing the contents of the file. * @param string $destination * A string containing the destination location. This must be a stream * wrapper URI. * @param int $replace * Replace behavior when the destination file already exists: * - FILE_EXISTS_REPLACE - Replace the existing file. * - FILE_EXISTS_RENAME - Append _{incrementing number} until the filename * is unique. * - FILE_EXISTS_ERROR - Do nothing and return FALSE. * * @return string * A string with the path of the resulting file, or FALSE on error. * * @throws \Drupal\Core\File\Exception\FileException * Implementation may throw FileException or its subtype on failure. * * @see file_save_data() */ public function saveData($data, $destination, $replace = self::EXISTS_RENAME); /** * Checks that the directory exists and is writable. * * Directories need to have execute permissions to be considered a directory * by FTP servers, etc. * * @param string $directory * A string reference containing the name of a directory path or URI. A * trailing slash will be trimmed from a path. * @param int $options * A bitmask to indicate if the directory should be created if it does * not exist (FileSystemInterface::CREATE_DIRECTORY) or made writable if it * is read-only (FileSystemInterface::MODIFY_PERMISSIONS). * * @return bool * TRUE if the directory exists (or was created) and is writable. FALSE * otherwise. */ public function prepareDirectory(&$directory, $options = self::MODIFY_PERMISSIONS); /** * Creates a full file path from a directory and filename. * * If a file with the specified name already exists, an alternative will be * used. * * @param string $basename * The filename. * @param string $directory * The directory or parent URI. * * @return string * File path consisting of $directory and a unique filename based off * of $basename. * * @throws \Drupal\Core\File\Exception\FileException * Implementation may throw FileException or its subtype on failure. */ public function createFilename($basename, $directory); /** * Determines the destination path for a file. * * @param string $destination * The desired final URI or filepath. * @param int $replace * Replace behavior when the destination file already exists. * - FileSystemInterface::EXISTS_REPLACE - Replace the existing file. * - FileSystemInterface::EXISTS_RENAME - Append _{incrementing number} * until the filename is unique. * - FileSystemInterface::EXISTS_ERROR - Do nothing and return FALSE. * * @return string|bool * The destination filepath, or FALSE if the file already exists * and FileSystemInterface::EXISTS_ERROR is specified. * * @throws \Drupal\Core\File\Exception\FileException * Implementation may throw FileException or its subtype on failure. */ public function getDestinationFilename($destination, $replace); }