aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/File/FileSystemInterface.php

   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    * Moves an uploaded file to a new location.
  12    *
  13    * PHP's move_uploaded_file() does not properly support streams if
  14    * open_basedir is enabled, so this function fills that gap.
  15    *
  16    * Compatibility: normal paths and stream wrappers.
  17    *
  18    * @param string $filename
  19    *   The filename of the uploaded file.
  20    * @param string $uri
  21    *   A string containing the destination URI of the file.
  22    *
  23    * @return bool
  24    *   TRUE on success, or FALSE on failure.
  25    *
  26    * @see move_uploaded_file()
  27    * @see https://www.drupal.org/node/515192
  28    * @ingroup php_wrappers
  29    */
  30   public function moveUploadedFile($filename, $uri);
  31
  32   /**
  33    * Sets the permissions on a file or directory.
  34    *
  35    * This function will use the file_chmod_directory and
  36    * file_chmod_file settings for the default modes for directories
  37    * and uploaded/generated files. By default these will give everyone read
  38    * access so that users accessing the files with a user account without the
  39    * webserver group (e.g. via FTP) can read these files, and give group write
  40    * permissions so webserver group members (e.g. a vhost account) can alter
  41    * files uploaded and owned by the webserver.
  42    *
  43    * PHP's chmod does not support stream wrappers so we use our wrapper
  44    * implementation which interfaces with chmod() by default. Contrib wrappers
  45    * may override this behavior in their implementations as needed.
  46    *
  47    * @param string $uri
  48    *   A string containing a URI file, or directory path.
  49    * @param int $mode
  50    *   Integer value for the permissions. Consult PHP chmod() documentation for
  51    *   more information.
  52    *
  53    * @return bool
  54    *   TRUE for success, FALSE in the event of an error.
  55    *
  56    * @ingroup php_wrappers
  57    */
  58   public function chmod($uri, $mode = NULL);
  59
  60   /**
  61    * Deletes a file.
  62    *
  63    * PHP's unlink() is broken on Windows, as it can fail to remove a file when
  64    * it has a read-only flag set.
  65    *
  66    * @param string $uri
  67    *   A URI or pathname.
  68    * @param resource $context
  69    *   Refer to http://php.net/manual/ref.stream.php
  70    *
  71    * @return bool
  72    *   Boolean TRUE on success, or FALSE on failure.
  73    *
  74    * @see unlink()
  75    * @ingroup php_wrappers
  76    */
  77   public function unlink($uri, $context = NULL);
  78
  79   /**
  80    * Resolves the absolute filepath of a local URI or filepath.
  81    *
  82    * The use of this method is discouraged, because it does not work for
  83    * remote URIs. Except in rare cases, URIs should not be manually resolved.
  84    *
  85    * Only use this function if you know that the stream wrapper in the URI uses
  86    * the local file system, and you need to pass an absolute path to a function
  87    * that is incompatible with stream URIs.
  88    *
  89    * @param string $uri
  90    *   A stream wrapper URI or a filepath, possibly including one or more
  91    *   symbolic links.
  92    *
  93    * @return string|false
  94    *   The absolute local filepath (with no symbolic links) or FALSE on failure.
  95    *
  96    * @see \Drupal\Core\StreamWrapper\StreamWrapperInterface::realpath()
  97    * @see http://php.net/manual/function.realpath.php
  98    * @ingroup php_wrappers
  99    */
 100   public function realpath($uri);
 101
 102   /**
 103    * Gets the name of the directory from a given path.
 104    *
 105    * PHP's dirname() does not properly pass streams, so this function fills that
 106    * gap. It is backwards compatible with normal paths and will use PHP's
 107    * dirname() as a fallback.
 108    *
 109    * Compatibility: normal paths and stream wrappers.
 110    *
 111    * @param string $uri
 112    *   A URI or path.
 113    *
 114    * @return string
 115    *   A string containing the directory name.
 116    *
 117    * @see dirname()
 118    * @see https://www.drupal.org/node/515192
 119    * @ingroup php_wrappers
 120    */
 121   public function dirname($uri);
 122
 123   /**
 124    * Gets the filename from a given path.
 125    *
 126    * PHP's basename() does not properly support streams or filenames beginning
 127    * with a non-US-ASCII character.
 128    *
 129    * @see http://bugs.php.net/bug.php?id=37738
 130    * @see basename()
 131    *
 132    * @ingroup php_wrappers
 133    */
 134   public function basename($uri, $suffix = NULL);
 135
 136   /**
 137    * Creates a directory, optionally creating missing components in the path to
 138    * the directory.
 139    *
 140    * When PHP's mkdir() creates a directory, the requested mode is affected by
 141    * the process's umask. This function overrides the umask and sets the mode
 142    * explicitly for all directory components created.
 143    *
 144    * @param string $uri
 145    *   A URI or pathname.
 146    * @param int $mode
 147    *   Mode given to created directories. Defaults to the directory mode
 148    *   configured in the Drupal installation. It must have a leading zero.
 149    * @param bool $recursive
 150    *   Create directories recursively, defaults to FALSE. Cannot work with a
 151    *   mode which denies writing or execution to the owner of the process.
 152    * @param resource $context
 153    *   Refer to http://php.net/manual/ref.stream.php
 154    *
 155    * @return bool
 156    *   Boolean TRUE on success, or FALSE on failure.
 157    *
 158    * @see mkdir()
 159    * @see https://www.drupal.org/node/515192
 160    * @ingroup php_wrappers
 161    *
 162    * @todo Update with open_basedir compatible recursion logic from
 163    *   \Drupal\Component\PhpStorage\FileStorage::ensureDirectory().
 164    */
 165   public function mkdir($uri, $mode = NULL, $recursive = FALSE, $context = NULL);
 166
 167   /**
 168    * Removes a directory.
 169    *
 170    * PHP's rmdir() is broken on Windows, as it can fail to remove a directory
 171    * when it has a read-only flag set.
 172    *
 173    * @param string $uri
 174    *   A URI or pathname.
 175    * @param resource $context
 176    *   Refer to http://php.net/manual/ref.stream.php
 177    *
 178    * @return bool
 179    *   Boolean TRUE on success, or FALSE on failure.
 180    *
 181    * @see rmdir()
 182    * @ingroup php_wrappers
 183    */
 184   public function rmdir($uri, $context = NULL);
 185
 186   /**
 187    * Creates a file with a unique filename in the specified directory.
 188    *
 189    * PHP's tempnam() does not return a URI like we want. This function will
 190    * return a URI if given a URI, or it will return a filepath if given a
 191    * filepath.
 192    *
 193    * Compatibility: normal paths and stream wrappers.
 194    *
 195    * @param string $directory
 196    *   The directory where the temporary filename will be created.
 197    * @param string $prefix
 198    *   The prefix of the generated temporary filename.
 199    *   Note: Windows uses only the first three characters of prefix.
 200    *
 201    * @return string|bool
 202    *   The new temporary filename, or FALSE on failure.
 203    *
 204    * @see tempnam()
 205    * @see https://www.drupal.org/node/515192
 206    * @ingroup php_wrappers
 207    */
 208   public function tempnam($directory, $prefix);
 209
 210   /**
 211    * Returns the scheme of a URI (e.g. a stream).
 212    *
 213    * @param string $uri
 214    *   A stream, referenced as "scheme://target" or "data:target".
 215    *
 216    * @return string|bool
 217    *   A string containing the name of the scheme, or FALSE if none. For
 218    *   example, the URI "public://example.txt" would return "public".
 219    *
 220    * @see file_uri_target()
 221    */
 222   public function uriScheme($uri);
 223
 224   /**
 225    * Checks that the scheme of a stream URI is valid.
 226    *
 227    * Confirms that there is a registered stream handler for the provided scheme
 228    * and that it is callable. This is useful if you want to confirm a valid
 229    * scheme without creating a new instance of the registered handler.
 230    *
 231    * @param string $scheme
 232    *   A URI scheme, a stream is referenced as "scheme://target".
 233    *
 234    * @return bool
 235    *   Returns TRUE if the string is the name of a validated stream, or FALSE if
 236    *   the scheme does not have a registered handler.
 237    */
 238   public function validScheme($scheme);
 239
 240 }