interface FileSystemInterface in Drupal 8
Same name and namespace in other branches
- 9 core/lib/Drupal/Core/File/FileSystemInterface.php \Drupal\Core\File\FileSystemInterface
Provides an interface for helpers that operate on files and stream wrappers.
Hierarchy
- interface \Drupal\Core\File\FileSystemInterface
Expanded class hierarchy of FileSystemInterface
All classes that implement FileSystemInterface
78 files declare their use of FileSystemInterface
- ArchiverManager.php in core/
lib/ Drupal/ Core/ Archiver/ ArchiverManager.php - AssetDumper.php in core/
lib/ Drupal/ Core/ Asset/ AssetDumper.php - color.module in core/
modules/ color/ color.module - Allows users to change the color scheme of themes.
- ConfigController.php in core/
modules/ config/ src/ Controller/ ConfigController.php - ConfigExportUITest.php in core/
modules/ config/ tests/ src/ Functional/ ConfigExportUITest.php
File
- core/
lib/ Drupal/ Core/ File/ FileSystemInterface.php, line 8
Namespace
Drupal\Core\FileView source
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".
*
* @deprecated in drupal:8.8.0 and is removed from drupal:9.0.0. Use
* Drupal\Core\StreamWrapper\StreamWrapperManagerInterface::getScheme()
* instead.
*
* @see https://www.drupal.org/node/3035273
*/
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.
*
* @deprecated in drupal:8.0.0 and is removed from drupal:9.0.0. Use
* Drupal\Core\StreamWrapper\StreamWrapperManagerInterface::isValidScheme()
* instead.
*
* @see https://www.drupal.org/node/3035273
*/
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. FileSystemInterface::EXISTS_REPLACE will replace the
* existing file. FileSystemInterface::EXISTS_ERROR will error out.
* FileSystemInterface::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:
* - FileSystemInterface::EXISTS_REPLACE - Replace the existing file.
* - FileSystemInterface::EXISTS_RENAME - Append _{incrementing number}
* until the filename is unique.
* - FileSystemInterface::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:
* - 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
* 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:
* - 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
* 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);
/**
* Gets the path of the configured temporary directory.
*
* If the path is not set, it will fall back to the OS-specific default if
* set, otherwise a directory under the public files directory. It will then
* set this as the configured directory.
*
* @return string
* A string containing the path to the temporary directory.
*/
public function getTempDirectory();
/**
* Finds all files that match a given mask in a given directory.
*
* Directories and files beginning with a dot are excluded; this prevents
* hidden files and directories (such as SVN working directories) from being
* scanned. Use the umask option to skip configuration directories to
* eliminate the possibility of accidentally exposing configuration
* information. Also, you can use the base directory, recurse, and min_depth
* options to improve performance by limiting how much of the filesystem has
* to be traversed.
*
* @param string $dir
* The base directory or URI to scan, without trailing slash.
* @param string $mask
* The preg_match() regular expression for files to be included.
* @param array $options
* An associative array of additional options, with the following elements:
* - 'nomask': The preg_match() regular expression for files to be excluded.
* Defaults to the 'file_scan_ignore_directories' setting.
* - 'callback': The callback function to call for each match. There is no
* default callback.
* - 'recurse': When TRUE, the directory scan will recurse the entire tree
* starting at the provided directory. Defaults to TRUE.
* - 'key': The key to be used for the returned associative array of files.
* Possible values are 'uri', for the file's URI; 'filename', for the
* basename of the file; and 'name' for the name of the file without the
* extension. Defaults to 'uri'.
* - 'min_depth': Minimum depth of directories to return files from.
* Defaults to 0.
*
* @return array
* An associative array (keyed on the chosen key) of objects with 'uri',
* 'filename', and 'name' properties corresponding to the matched files.
*
* @throws \Drupal\Core\File\Exception\NotRegularDirectoryException
* If the directory does not exist.
*/
public function scanDirectory($dir, $mask, array $options = []);
}Members
Name |
Modifiers | Type | Description | Overrides |
|---|---|---|---|---|
|
FileSystemInterface:: |
public | function | Gets the filename from a given path. | 1 |
|
FileSystemInterface:: |
public | function | Sets the permissions on a file or directory. | 1 |
|
FileSystemInterface:: |
public | function | Copies a file to a new location without invoking the file API. | 1 |
|
FileSystemInterface:: |
public | function | Creates a full file path from a directory and filename. | 1 |
|
FileSystemInterface:: |
constant | Flag used by ::prepareDirectory() -- create directory if not present. | ||
|
FileSystemInterface:: |
public | function | Deletes a file without database changes or hook invocations. | 1 |
|
FileSystemInterface:: |
public | function | Deletes all files and directories in the specified filepath recursively. | 1 |
|
FileSystemInterface:: |
public | function | Gets the name of the directory from a given path. | 1 |
|
FileSystemInterface:: |
constant | Flag for dealing with existing files: Do nothing and return FALSE. | ||
|
FileSystemInterface:: |
constant | Flag for dealing with existing files: Appends number until name is unique. | ||
|
FileSystemInterface:: |
constant | Flag for dealing with existing files: Replace the existing file. | ||
|
FileSystemInterface:: |
public | function | Determines the destination path for a file. | 1 |
|
FileSystemInterface:: |
public | function | Gets the path of the configured temporary directory. | 1 |
|
FileSystemInterface:: |
public | function | Creates a directory, optionally creating missing components in the path to the directory. | 1 |
|
FileSystemInterface:: |
constant | Flag used by ::prepareDirectory() -- file permissions may be changed. | ||
|
FileSystemInterface:: |
public | function | Moves a file to a new location without database changes or hook invocation. | 1 |
|
FileSystemInterface:: |
public | function | Moves an uploaded file to a new location. | 1 |
|
FileSystemInterface:: |
public | function | Checks that the directory exists and is writable. | 1 |
|
FileSystemInterface:: |
public | function | Resolves the absolute filepath of a local URI or filepath. | 1 |
|
FileSystemInterface:: |
public | function | Removes a directory. | 1 |
|
FileSystemInterface:: |
public | function | Saves a file to the specified destination without invoking file API. | 1 |
|
FileSystemInterface:: |
public | function | Finds all files that match a given mask in a given directory. | 1 |
|
FileSystemInterface:: |
public | function | Creates a file with a unique filename in the specified directory. | 1 |
|
FileSystemInterface:: |
public | function | Deletes a file. | 1 |
|
FileSystemInterface:: |
public | function | Returns the scheme of a URI (e.g. a stream). | 1 |
|
FileSystemInterface:: |
public | function | Checks that the scheme of a stream URI is valid. | 1 |