[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   *
   4   * This file is part of the phpBB Forum Software package.
   5   *
   6   * @copyright (c) phpBB Limited <https://www.phpbb.com>
   7   * @license GNU General Public License, version 2 (GPL-2.0)
   8   *
   9   * For full copyright and license information, please see
  10   * the docs/CREDITS.txt file.
  11   *
  12   */
  13  
  14  namespace phpbb\filesystem;
  15  
  16  /**
  17   * Interface for phpBB's filesystem service
  18   */
  19  interface filesystem_interface
  20  {
  21      /**
  22       * chmod all permissions flag
  23       *
  24       * @var int
  25       */
  26      const CHMOD_ALL = 7;
  27  
  28      /**
  29       * chmod read permissions flag
  30       *
  31       * @var int
  32       */
  33      const CHMOD_READ = 4;
  34  
  35      /**
  36       * chmod write permissions flag
  37       *
  38       * @var int
  39       */
  40      const CHMOD_WRITE = 2;
  41  
  42      /**
  43       * chmod execute permissions flag
  44       *
  45       * @var int
  46       */
  47      const CHMOD_EXECUTE = 1;
  48  
  49      /**
  50       * Change owner group of files/directories
  51       *
  52       * @param string|array|\Traversable    $files        The file(s)/directorie(s) to change group
  53       * @param string                    $group        The group that should own the files/directories
  54       * @param bool                         $recursive    If the group should be changed recursively
  55       * @throws \phpbb\filesystem\exception\filesystem_exception    the filename which triggered the error can be
  56       *                                                             retrieved by filesystem_exception::get_filename()
  57       */
  58  	public function chgrp($files, $group, $recursive = false);
  59  
  60      /**
  61       * Global function for chmodding directories and files for internal use
  62       *
  63       * The function accepts filesystem_interface::CHMOD_ flags in the permission argument
  64       * or the user can specify octal values (or any integer if it makes sense). All directories will have
  65       * an execution bit appended, if the user group (owner, group or other) has any bit specified.
  66       *
  67       * @param string|array|\Traversable    $files                The file/directory to be chmodded
  68       * @param int                        $perms                Permissions to set
  69       * @param bool                        $recursive            If the permissions should be changed recursively
  70       * @param bool                        $force_chmod_link    Try to apply permissions to symlinks as well
  71       *
  72       * @throws \phpbb\filesystem\exception\filesystem_exception    the filename which triggered the error can be
  73       *                                                             retrieved by filesystem_exception::get_filename()
  74       */
  75  	public function chmod($files, $perms = null, $recursive = false, $force_chmod_link = false);
  76  
  77      /**
  78       * Change owner group of files/directories
  79       *
  80       * @param string|array|\Traversable    $files        The file(s)/directorie(s) to change group
  81       * @param string                    $user        The owner user name
  82       * @param bool                         $recursive    Whether change the owner recursively or not
  83       *
  84       * @throws \phpbb\filesystem\exception\filesystem_exception    the filename which triggered the error can be
  85       *                                                             retrieved by filesystem_exception::get_filename()
  86       */
  87  	public function chown($files, $user, $recursive = false);
  88  
  89      /**
  90       * Eliminates useless . and .. components from specified path.
  91       *
  92       * @param string $path Path to clean
  93       *
  94       * @return string Cleaned path
  95       */
  96  	public function clean_path($path);
  97  
  98      /**
  99       * Copies a file.
 100       *
 101       * This method only copies the file if the origin file is newer than the target file.
 102       *
 103       * By default, if the target already exists, it is not overridden.
 104       *
 105       * @param string    $origin_file    The original filename
 106       * @param string    $target_file    The target filename
 107       * @param bool        $override        Whether to override an existing file or not
 108       *
 109       * @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be copied
 110       */
 111  	public function copy($origin_file, $target_file, $override = false);
 112  
 113      /**
 114       * Atomically dumps content into a file.
 115       *
 116       * @param string    $filename    The file to be written to.
 117       * @param string    $content    The data to write into the file.
 118       *
 119       * @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be written
 120       */
 121  	public function dump_file($filename, $content);
 122  
 123      /**
 124       * Checks the existence of files or directories.
 125       *
 126       * @param string|array|\Traversable    $files    files/directories to check
 127       *
 128       * @return bool    Returns true if all files/directories exist, false otherwise
 129       */
 130  	public function exists($files);
 131  
 132      /**
 133       * Checks if a path is absolute or not
 134       *
 135       * @param string    $path    Path to check
 136       *
 137       * @return    bool    true if the path is absolute, false otherwise
 138       */
 139  	public function is_absolute_path($path);
 140  
 141      /**
 142       * Checks if files/directories are readable
 143       *
 144       * @param string|array|\Traversable    $files        files/directories to check
 145       * @param bool                        $recursive    Whether or not directories should be checked recursively
 146       *
 147       * @return bool True when the files/directories are readable, otherwise false.
 148       */
 149  	public function is_readable($files, $recursive = false);
 150  
 151      /**
 152       * Test if a file/directory is writable
 153       *
 154       * @param string|array|\Traversable    $files        files/directories to perform write test on
 155       * @param bool                        $recursive    Whether or not directories should be checked recursively
 156       *
 157       * @return bool True when the files/directories are writable, otherwise false.
 158       */
 159  	public function is_writable($files, $recursive = false);
 160  
 161      /**
 162       * Given an existing path, convert it to a path relative to a given starting path
 163       *
 164       * @param string $end_path        Absolute path of target
 165       * @param string $start_path    Absolute path where traversal begins
 166       *
 167       * @return string Path of target relative to starting path
 168       */
 169  	public function make_path_relative($end_path, $start_path);
 170  
 171      /**
 172       * Mirrors a directory to another.
 173       *
 174       * @param string        $origin_dir    The origin directory
 175       * @param string        $target_dir    The target directory
 176       * @param \Traversable    $iterator    A Traversable instance
 177       * @param array            $options    An array of boolean options
 178       *                                    Valid options are:
 179       *                                        - $options['override'] Whether to override an existing file on copy or not (see copy())
 180       *                                        - $options['copy_on_windows'] Whether to copy files instead of links on Windows (see symlink())
 181       *                                        - $options['delete'] Whether to delete files that are not in the source directory (defaults to false)
 182       *
 183       * @throws \phpbb\filesystem\exception\filesystem_exception When the file cannot be copied.
 184       *                                                             The filename which triggered the error can be
 185       *                                                             retrieved by filesystem_exception::get_filename()
 186       */
 187  	public function mirror($origin_dir, $target_dir, \Traversable $iterator = null, $options = array());
 188  
 189      /**
 190       * Creates a directory recursively.
 191       *
 192       * @param string|array|\Traversable    $dirs    The directory path
 193       * @param int                        $mode    The directory mode
 194       *
 195       * @throws \phpbb\filesystem\exception\filesystem_exception On any directory creation failure
 196       *                                                             The filename which triggered the error can be
 197       *                                                             retrieved by filesystem_exception::get_filename()
 198       */
 199  	public function mkdir($dirs, $mode = 0777);
 200  
 201      /**
 202       * Global function for chmodding directories and files for internal use
 203       *
 204       * This function determines owner and group whom the file belongs to and user and group of PHP and then set safest possible file permissions.
 205       * The function determines owner and group from common.php file and sets the same to the provided file.
 206       * The function uses bit fields to build the permissions.
 207       * The function sets the appropriate execute bit on directories.
 208       *
 209       * Supported constants representing bit fields are:
 210       *
 211       * filesystem_interface::CHMOD_ALL - all permissions (7)
 212       * filesystem_interface::CHMOD_READ - read permission (4)
 213       * filesystem_interface::CHMOD_WRITE - write permission (2)
 214       * filesystem_interface::CHMOD_EXECUTE - execute permission (1)
 215       *
 216       * NOTE: The function uses POSIX extension and fileowner()/filegroup() functions. If any of them is disabled, this function tries to build proper permissions, by calling is_readable() and is_writable() functions.
 217       *
 218       * @param string|array|\Traversable    $file                The file/directory to be chmodded
 219       * @param int                        $perms                Permissions to set
 220       * @param bool                        $recursive            If the permissions should be changed recursively
 221       * @param bool                        $force_chmod_link    Try to apply permissions to symlinks as well
 222       *
 223       * @throws \phpbb\filesystem\exception\filesystem_exception    the filename which triggered the error can be
 224       *                                                             retrieved by filesystem_exception::get_filename()
 225       */
 226  	public function phpbb_chmod($file, $perms = null, $recursive = false, $force_chmod_link = false);
 227  
 228      /**
 229       * A wrapper for PHP's realpath
 230       *
 231       * Try to resolve realpath when PHP's realpath is not available, or
 232       * known to be buggy.
 233       *
 234       * @param string    $path    Path to resolve
 235       *
 236       * @return string    Resolved path
 237       */
 238  	public function realpath($path);
 239  
 240      /**
 241       * Removes files or directories.
 242       *
 243       * @param string|array|\Traversable    $files    A filename, an array of files, or a \Traversable instance to remove
 244       *
 245       * @throws \phpbb\filesystem\exception\filesystem_exception When removal fails.
 246       *                                                             The filename which triggered the error can be
 247       *                                                             retrieved by filesystem_exception::get_filename()
 248       */
 249  	public function remove($files);
 250  
 251      /**
 252       * Renames a file or a directory.
 253       *
 254       * @param string    $origin        The origin filename or directory
 255       * @param string    $target        The new filename or directory
 256       * @param bool        $overwrite    Whether to overwrite the target if it already exists
 257       *
 258       * @throws \phpbb\filesystem\exception\filesystem_exception    When target file or directory already exists,
 259       *                                                             or origin cannot be renamed.
 260       */
 261  	public function rename($origin, $target, $overwrite = false);
 262  
 263      /**
 264       * Creates a symbolic link or copy a directory.
 265       *
 266       * @param string    $origin_dir            The origin directory path
 267       * @param string    $target_dir            The symbolic link name
 268       * @param bool        $copy_on_windows    Whether to copy files if on Windows
 269       *
 270       * @throws \phpbb\filesystem\exception\filesystem_exception When symlink fails
 271       */
 272  	public function symlink($origin_dir, $target_dir, $copy_on_windows = false);
 273  
 274      /**
 275       * Sets access and modification time of file.
 276       *
 277       * @param string|array|\Traversable    $files            A filename, an array of files, or a \Traversable instance to create
 278       * @param int                        $time            The touch time as a Unix timestamp
 279       * @param int                        $access_time    The access time as a Unix timestamp
 280       *
 281       * @throws \phpbb\filesystem\exception\filesystem_exception    When touch fails
 282       */
 283  	public function touch($files, $time = null, $access_time = null);
 284  }