"Fossies" - the Fresh Open Source Software Archive

Member "drupal-8.9.10/core/lib/Drupal/Core/File/FileSystemInterface.php" (26 Nov 2020, 19413 Bytes) of package /linux/www/drupal-8.9.10.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) PHP source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "FileSystemInterface.php" see the Fossies "Dox" file reference documentation.

    1 <?php
    2 
    3 namespace Drupal\Core\File;
    4 
    5 /**
    6  * Provides an interface for helpers that operate on files and stream wrappers.
    7  */
    8 interface FileSystemInterface {
    9 
   10   /**
   11    * Flag for dealing with existing files: Appends number until name is unique.
   12    */
   13   const EXISTS_RENAME = 0;
   14 
   15   /**
   16    * Flag for dealing with existing files: Replace the existing file.
   17    */
   18   const EXISTS_REPLACE = 1;
   19 
   20   /**
   21    * Flag for dealing with existing files: Do nothing and return FALSE.
   22    */
   23   const EXISTS_ERROR = 2;
   24 
   25   /**
   26    * Flag used by ::prepareDirectory() -- create directory if not present.
   27    */
   28   const CREATE_DIRECTORY = 1;
   29 
   30   /**
   31    * Flag used by ::prepareDirectory() -- file permissions may be changed.
   32    */
   33   const MODIFY_PERMISSIONS = 2;
   34 
   35   /**
   36    * Moves an uploaded file to a new location.
   37    *
   38    * PHP's move_uploaded_file() does not properly support streams if
   39    * open_basedir is enabled, so this function fills that gap.
   40    *
   41    * Compatibility: normal paths and stream wrappers.
   42    *
   43    * @param string $filename
   44    *   The filename of the uploaded file.
   45    * @param string $uri
   46    *   A string containing the destination URI of the file.
   47    *
   48    * @return bool
   49    *   TRUE on success, or FALSE on failure.
   50    *
   51    * @see move_uploaded_file()
   52    * @see https://www.drupal.org/node/515192
   53    * @ingroup php_wrappers
   54    */
   55   public function moveUploadedFile($filename, $uri);
   56 
   57   /**
   58    * Sets the permissions on a file or directory.
   59    *
   60    * This function will use the file_chmod_directory and
   61    * file_chmod_file settings for the default modes for directories
   62    * and uploaded/generated files. By default these will give everyone read
   63    * access so that users accessing the files with a user account without the
   64    * webserver group (e.g. via FTP) can read these files, and give group write
   65    * permissions so webserver group members (e.g. a vhost account) can alter
   66    * files uploaded and owned by the webserver.
   67    *
   68    * PHP's chmod does not support stream wrappers so we use our wrapper
   69    * implementation which interfaces with chmod() by default. Contrib wrappers
   70    * may override this behavior in their implementations as needed.
   71    *
   72    * @param string $uri
   73    *   A string containing a URI file, or directory path.
   74    * @param int $mode
   75    *   Integer value for the permissions. Consult PHP chmod() documentation for
   76    *   more information.
   77    *
   78    * @return bool
   79    *   TRUE for success, FALSE in the event of an error.
   80    *
   81    * @ingroup php_wrappers
   82    */
   83   public function chmod($uri, $mode = NULL);
   84 
   85   /**
   86    * Deletes a file.
   87    *
   88    * PHP's unlink() is broken on Windows, as it can fail to remove a file when
   89    * it has a read-only flag set.
   90    *
   91    * @param string $uri
   92    *   A URI or pathname.
   93    * @param resource $context
   94    *   Refer to http://php.net/manual/ref.stream.php
   95    *
   96    * @return bool
   97    *   Boolean TRUE on success, or FALSE on failure.
   98    *
   99    * @see unlink()
  100    * @ingroup php_wrappers
  101    */
  102   public function unlink($uri, $context = NULL);
  103 
  104   /**
  105    * Resolves the absolute filepath of a local URI or filepath.
  106    *
  107    * The use of this method is discouraged, because it does not work for
  108    * remote URIs. Except in rare cases, URIs should not be manually resolved.
  109    *
  110    * Only use this function if you know that the stream wrapper in the URI uses
  111    * the local file system, and you need to pass an absolute path to a function
  112    * that is incompatible with stream URIs.
  113    *
  114    * @param string $uri
  115    *   A stream wrapper URI or a filepath, possibly including one or more
  116    *   symbolic links.
  117    *
  118    * @return string|false
  119    *   The absolute local filepath (with no symbolic links) or FALSE on failure.
  120    *
  121    * @see \Drupal\Core\StreamWrapper\StreamWrapperInterface::realpath()
  122    * @see http://php.net/manual/function.realpath.php
  123    * @ingroup php_wrappers
  124    */
  125   public function realpath($uri);
  126 
  127   /**
  128    * Gets the name of the directory from a given path.
  129    *
  130    * PHP's dirname() does not properly pass streams, so this function fills that
  131    * gap. It is backwards compatible with normal paths and will use PHP's
  132    * dirname() as a fallback.
  133    *
  134    * Compatibility: normal paths and stream wrappers.
  135    *
  136    * @param string $uri
  137    *   A URI or path.
  138    *
  139    * @return string
  140    *   A string containing the directory name.
  141    *
  142    * @see dirname()
  143    * @see https://www.drupal.org/node/515192
  144    * @ingroup php_wrappers
  145    */
  146   public function dirname($uri);
  147 
  148   /**
  149    * Gets the filename from a given path.
  150    *
  151    * PHP's basename() does not properly support streams or filenames beginning
  152    * with a non-US-ASCII character.
  153    *
  154    * @see http://bugs.php.net/bug.php?id=37738
  155    * @see basename()
  156    *
  157    * @ingroup php_wrappers
  158    */
  159   public function basename($uri, $suffix = NULL);
  160 
  161   /**
  162    * Creates a directory, optionally creating missing components in the path to
  163    * the directory.
  164    *
  165    * When PHP's mkdir() creates a directory, the requested mode is affected by
  166    * the process's umask. This function overrides the umask and sets the mode
  167    * explicitly for all directory components created.
  168    *
  169    * @param string $uri
  170    *   A URI or pathname.
  171    * @param int $mode
  172    *   Mode given to created directories. Defaults to the directory mode
  173    *   configured in the Drupal installation. It must have a leading zero.
  174    * @param bool $recursive
  175    *   Create directories recursively, defaults to FALSE. Cannot work with a
  176    *   mode which denies writing or execution to the owner of the process.
  177    * @param resource $context
  178    *   Refer to http://php.net/manual/ref.stream.php
  179    *
  180    * @return bool
  181    *   Boolean TRUE on success, or FALSE on failure.
  182    *
  183    * @see mkdir()
  184    * @see https://www.drupal.org/node/515192
  185    * @ingroup php_wrappers
  186    *
  187    * @todo Update with open_basedir compatible recursion logic from
  188    *   \Drupal\Component\PhpStorage\FileStorage::ensureDirectory().
  189    */
  190   public function mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL);
  191 
  192   /**
  193    * Removes a directory.
  194    *
  195    * PHP's rmdir() is broken on Windows, as it can fail to remove a directory
  196    * when it has a read-only flag set.
  197    *
  198    * @param string $uri
  199    *   A URI or pathname.
  200    * @param resource $context
  201    *   Refer to http://php.net/manual/ref.stream.php
  202    *
  203    * @return bool
  204    *   Boolean TRUE on success, or FALSE on failure.
  205    *
  206    * @see rmdir()
  207    * @ingroup php_wrappers
  208    */
  209   public function rmdir($uri, $context = NULL);
  210 
  211   /**
  212    * Creates a file with a unique filename in the specified directory.
  213    *
  214    * PHP's tempnam() does not return a URI like we want. This function will
  215    * return a URI if given a URI, or it will return a filepath if given a
  216    * filepath.
  217    *
  218    * Compatibility: normal paths and stream wrappers.
  219    *
  220    * @param string $directory
  221    *   The directory where the temporary filename will be created.
  222    * @param string $prefix
  223    *   The prefix of the generated temporary filename.
  224    *   Note: Windows uses only the first three characters of prefix.
  225    *
  226    * @return string|bool
  227    *   The new temporary filename, or FALSE on failure.
  228    *
  229    * @see tempnam()
  230    * @see https://www.drupal.org/node/515192
  231    * @ingroup php_wrappers
  232    */
  233   public function tempnam($directory, $prefix);
  234 
  235   /**
  236    * Returns the scheme of a URI (e.g. a stream).
  237    *
  238    * @param string $uri
  239    *   A stream, referenced as "scheme://target" or "data:target".
  240    *
  241    * @return string|bool
  242    *   A string containing the name of the scheme, or FALSE if none. For
  243    *   example, the URI "public://example.txt" would return "public".
  244    *
  245    * @deprecated in drupal:8.8.0 and is removed from drupal:9.0.0. Use
  246    *   Drupal\Core\StreamWrapper\StreamWrapperManagerInterface::getScheme()
  247    *   instead.
  248    *
  249    * @see https://www.drupal.org/node/3035273
  250    */
  251   public function uriScheme($uri);
  252 
  253   /**
  254    * Checks that the scheme of a stream URI is valid.
  255    *
  256    * Confirms that there is a registered stream handler for the provided scheme
  257    * and that it is callable. This is useful if you want to confirm a valid
  258    * scheme without creating a new instance of the registered handler.
  259    *
  260    * @param string $scheme
  261    *   A URI scheme, a stream is referenced as "scheme://target".
  262    *
  263    * @return bool
  264    *   Returns TRUE if the string is the name of a validated stream, or FALSE if
  265    *   the scheme does not have a registered handler.
  266    *
  267    * @deprecated in drupal:8.0.0 and is removed from drupal:9.0.0. Use
  268    *   Drupal\Core\StreamWrapper\StreamWrapperManagerInterface::isValidScheme()
  269    *   instead.
  270    *
  271    * @see https://www.drupal.org/node/3035273
  272    */
  273   public function validScheme($scheme);
  274 
  275   /**
  276    * Copies a file to a new location without invoking the file API.
  277    *
  278    * This is a powerful function that in many ways performs like an advanced
  279    * version of copy().
  280    * - Checks if $source and $destination are valid and readable/writable.
  281    * - If file already exists in $destination either the call will error out,
  282    *   replace the file or rename the file based on the $replace parameter.
  283    * - If the $source and $destination are equal, the behavior depends on the
  284    *   $replace parameter. FileSystemInterface::EXISTS_REPLACE will replace the
  285    *   existing file. FileSystemInterface::EXISTS_ERROR will error out.
  286    *   FileSystemInterface::EXISTS_RENAME will rename the file until the
  287    *   $destination is unique.
  288    * - Provides a fallback using realpaths if the move fails using stream
  289    *   wrappers. This can occur because PHP's copy() function does not properly
  290    *   support streams if open_basedir is enabled. See
  291    *   https://bugs.php.net/bug.php?id=60456
  292    *
  293    * @param string $source
  294    *   A string specifying the filepath or URI of the source file.
  295    * @param string $destination
  296    *   A URI containing the destination that $source should be copied to. The
  297    *   URI may be a bare filepath (without a scheme).
  298    * @param int $replace
  299    *   Replace behavior when the destination file already exists:
  300    *   - FileSystemInterface::EXISTS_REPLACE - Replace the existing file.
  301    *   - FileSystemInterface::EXISTS_RENAME - Append _{incrementing number}
  302    *     until the filename is unique.
  303    *   - FileSystemInterface::EXISTS_ERROR - Throw an exception.
  304    *
  305    * @return string
  306    *   The path to the new file.
  307    *
  308    * @throws \Drupal\Core\File\Exception\FileException
  309    *   Implementation may throw FileException or its subtype on failure.
  310    */
  311   public function copy($source, $destination, $replace = self::EXISTS_RENAME);
  312 
  313   /**
  314    * Deletes a file without database changes or hook invocations.
  315    *
  316    * This function should be used when the file to be deleted does not have an
  317    * entry recorded in the files table.
  318    *
  319    * @param string $path
  320    *   A string containing a file path or (streamwrapper) URI.
  321    *
  322    * @throws \Drupal\Core\File\Exception\FileException
  323    *   Implementation may throw FileException or its subtype on failure.
  324    */
  325   public function delete($path);
  326 
  327   /**
  328    * Deletes all files and directories in the specified filepath recursively.
  329    *
  330    * If the specified path is a directory then the function is called
  331    * recursively to process the contents. Once the contents have been removed
  332    * the directory is also removed.
  333    *
  334    * If the specified path is a file then it will be processed with delete()
  335    * method.
  336    *
  337    * Note that this only deletes visible files with write permission.
  338    *
  339    * @param string $path
  340    *   A string containing either an URI or a file or directory path.
  341    * @param callable|null $callback
  342    *   Callback function to run on each file prior to deleting it and on each
  343    *   directory prior to traversing it. For example, can be used to modify
  344    *   permissions.
  345    *
  346    * @throws \Drupal\Core\File\Exception\FileException
  347    *   Implementation may throw FileException or its subtype on failure.
  348    */
  349   public function deleteRecursive($path, callable $callback = NULL);
  350 
  351   /**
  352    * Moves a file to a new location without database changes or hook invocation.
  353    *
  354    * This is a powerful function that in many ways performs like an advanced
  355    * version of rename().
  356    * - Checks if $source and $destination are valid and readable/writable.
  357    * - Checks that $source is not equal to $destination; if they are an error
  358    *   is reported.
  359    * - If file already exists in $destination either the call will error out,
  360    *   replace the file or rename the file based on the $replace parameter.
  361    * - Works around a PHP bug where rename() does not properly support streams
  362    *   if safe_mode or open_basedir are enabled.
  363    *
  364    * @param string $source
  365    *   A string specifying the filepath or URI of the source file.
  366    * @param string $destination
  367    *   A URI containing the destination that $source should be moved to. The
  368    *   URI may be a bare filepath (without a scheme) and in that case the
  369    *   default scheme (public://) will be used.
  370    * @param int $replace
  371    *   Replace behavior when the destination file already exists:
  372    *   - FileSystemInterface::EXISTS_REPLACE - Replace the existing file.
  373    *   - FileSystemInterface::EXISTS_RENAME - Append _{incrementing number}
  374    *     until the filename is unique.
  375    *   - FileSystemInterface::EXISTS_ERROR - Do nothing and return FALSE.
  376    *
  377    * @return string
  378    *   The path to the new file.
  379    *
  380    * @throws \Drupal\Core\File\Exception\FileException
  381    *   Implementation may throw FileException or its subtype on failure.
  382    *
  383    * @see https://bugs.php.net/bug.php?id=60456
  384    */
  385   public function move($source, $destination, $replace = self::EXISTS_RENAME);
  386 
  387   /**
  388    * Saves a file to the specified destination without invoking file API.
  389    *
  390    * This function is identical to file_save_data() except the file will not be
  391    * saved to the {file_managed} table and none of the file_* hooks will be
  392    * called.
  393    *
  394    * @param string $data
  395    *   A string containing the contents of the file.
  396    * @param string $destination
  397    *   A string containing the destination location. This must be a stream
  398    *   wrapper URI.
  399    * @param int $replace
  400    *   Replace behavior when the destination file already exists:
  401    *   - FileSystemInterface::EXISTS_REPLACE - Replace the existing file.
  402    *   - FileSystemInterface::EXISTS_RENAME - Append _{incrementing number}
  403    *     until the filename is unique.
  404    *   - FileSystemInterface::EXISTS_ERROR - Do nothing and return FALSE.
  405    *
  406    * @return string
  407    *   A string with the path of the resulting file, or FALSE on error.
  408    *
  409    * @throws \Drupal\Core\File\Exception\FileException
  410    *   Implementation may throw FileException or its subtype on failure.
  411    *
  412    * @see file_save_data()
  413    */
  414   public function saveData($data, $destination, $replace = self::EXISTS_RENAME);
  415 
  416   /**
  417    * Checks that the directory exists and is writable.
  418    *
  419    * Directories need to have execute permissions to be considered a directory
  420    * by FTP servers, etc.
  421    *
  422    * @param string $directory
  423    *   A string reference containing the name of a directory path or URI. A
  424    *   trailing slash will be trimmed from a path.
  425    * @param int $options
  426    *   A bitmask to indicate if the directory should be created if it does
  427    *   not exist (FileSystemInterface::CREATE_DIRECTORY) or made writable if it
  428    *   is read-only (FileSystemInterface::MODIFY_PERMISSIONS).
  429    *
  430    * @return bool
  431    *   TRUE if the directory exists (or was created) and is writable. FALSE
  432    *   otherwise.
  433    */
  434   public function prepareDirectory(&$directory, $options = self::MODIFY_PERMISSIONS);
  435 
  436   /**
  437    * Creates a full file path from a directory and filename.
  438    *
  439    * If a file with the specified name already exists, an alternative will be
  440    * used.
  441    *
  442    * @param string $basename
  443    *   The filename.
  444    * @param string $directory
  445    *   The directory or parent URI.
  446    *
  447    * @return string
  448    *   File path consisting of $directory and a unique filename based off
  449    *   of $basename.
  450    *
  451    * @throws \Drupal\Core\File\Exception\FileException
  452    *   Implementation may throw FileException or its subtype on failure.
  453    */
  454   public function createFilename($basename, $directory);
  455 
  456   /**
  457    * Determines the destination path for a file.
  458    *
  459    * @param string $destination
  460    *   The desired final URI or filepath.
  461    * @param int $replace
  462    *   Replace behavior when the destination file already exists.
  463    *   - FileSystemInterface::EXISTS_REPLACE - Replace the existing file.
  464    *   - FileSystemInterface::EXISTS_RENAME - Append _{incrementing number}
  465    *     until the filename is unique.
  466    *   - FileSystemInterface::EXISTS_ERROR - Do nothing and return FALSE.
  467    *
  468    * @return string|bool
  469    *   The destination filepath, or FALSE if the file already exists
  470    *   and FileSystemInterface::EXISTS_ERROR is specified.
  471    *
  472    * @throws \Drupal\Core\File\Exception\FileException
  473    *   Implementation may throw FileException or its subtype on failure.
  474    */
  475   public function getDestinationFilename($destination, $replace);
  476 
  477   /**
  478    * Gets the path of the configured temporary directory.
  479    *
  480    * If the path is not set, it will fall back to the OS-specific default if
  481    * set, otherwise a directory under the public files directory. It will then
  482    * set this as the configured directory.
  483    *
  484    * @return string
  485    *   A string containing the path to the temporary directory.
  486    */
  487   public function getTempDirectory();
  488 
  489   /**
  490    * Finds all files that match a given mask in a given directory.
  491    *
  492    * Directories and files beginning with a dot are excluded; this prevents
  493    * hidden files and directories (such as SVN working directories) from being
  494    * scanned. Use the umask option to skip configuration directories to
  495    * eliminate the possibility of accidentally exposing configuration
  496    * information. Also, you can use the base directory, recurse, and min_depth
  497    * options to improve performance by limiting how much of the filesystem has
  498    * to be traversed.
  499    *
  500    * @param string $dir
  501    *   The base directory or URI to scan, without trailing slash.
  502    * @param string $mask
  503    *   The preg_match() regular expression for files to be included.
  504    * @param array $options
  505    *   An associative array of additional options, with the following elements:
  506    *   - 'nomask': The preg_match() regular expression for files to be excluded.
  507    *     Defaults to the 'file_scan_ignore_directories' setting.
  508    *   - 'callback': The callback function to call for each match. There is no
  509    *     default callback.
  510    *   - 'recurse': When TRUE, the directory scan will recurse the entire tree
  511    *     starting at the provided directory. Defaults to TRUE.
  512    *   - 'key': The key to be used for the returned associative array of files.
  513    *     Possible values are 'uri', for the file's URI; 'filename', for the
  514    *     basename of the file; and 'name' for the name of the file without the
  515    *     extension. Defaults to 'uri'.
  516    *   - 'min_depth': Minimum depth of directories to return files from.
  517    *     Defaults to 0.
  518    *
  519    * @return array
  520    *   An associative array (keyed on the chosen key) of objects with 'uri',
  521    *   'filename', and 'name' properties corresponding to the matched files.
  522    *
  523    * @throws \Drupal\Core\File\Exception\NotRegularDirectoryException
  524    *   If the directory does not exist.
  525    */
  526   public function scanDirectory($dir, $mask, array $options = []);
  527 
  528 }