typo3/sysext/core/Classes/Resource/Driver/DriverInterface.php

   1 <?php
   2 namespace TYPO3\CMS\Core\Resource\Driver;
   3
   4 /*
   5  * This file is part of the TYPO3 CMS project.
   6  *
   7  * It is free software; you can redistribute it and/or modify it under
   8  * the terms of the GNU General Public License, either version 2
   9  * of the License, or any later version.
  10  *
  11  * For the full copyright and license information, please read the
  12  * LICENSE.txt file that was distributed with this source code.
  13  *
  14  * The TYPO3 project - inspiring people to share!
  15  */
  16
  17
  18 /**
  19  * An interface Drivers have to implement to fulfil the needs
  20  * of the FAL API.
  21  */
  22 interface DriverInterface {
  23
  24         /**
  25          * Processes the configuration for this driver.
  26          * @return void
  27          */
  28         public function processConfiguration();
  29
  30         /**
  31          * Sets the storage uid the driver belongs to
  32          *
  33          * @param int $storageUid
  34          * @return void
  35          */
  36         public function setStorageUid($storageUid);
  37
  38         /**
  39          * Initializes this object. This is called by the storage after the driver
  40          * has been attached.
  41          *
  42          * @return void
  43          */
  44         public function initialize();
  45
  46         /**
  47          * Returns the capabilities of this driver.
  48          *
  49          * @return int
  50          * @see Storage::CAPABILITY_* constants
  51          */
  52         public function getCapabilities();
  53
  54         /**
  55          * Merges the capabilities merged by the user at the storage
  56          * configuration into the actual capabilities of the driver
  57          * and returns the result.
  58          *
  59          * @param int $capabilities
  60          * @return int
  61          */
  62         public function mergeConfigurationCapabilities($capabilities);
  63
  64         /**
  65          * Returns TRUE if this driver has the given capability.
  66          *
  67          * @param int $capability A capability, as defined in a CAPABILITY_* constant
  68          * @return bool
  69          */
  70         public function hasCapability($capability);
  71
  72         /**
  73          * Returns TRUE if this driver uses case-sensitive identifiers. NOTE: This
  74          * is a configurable setting, but the setting does not change the way the
  75          * underlying file system treats the identifiers; the setting should
  76          * therefore always reflect the file system and not try to change its
  77          * behaviour
  78          *
  79          * @return bool
  80          */
  81         public function isCaseSensitiveFileSystem();
  82
  83         /**
  84          * Cleans a fileName from not allowed characters
  85          *
  86          * @param string $fileName
  87          * @param string $charset Charset of the a fileName
  88          *                        (defaults to current charset; depending on context)
  89          * @return string the cleaned filename
  90          */
  91         public function sanitizeFileName($fileName, $charset = '');
  92
  93         /**
  94          * Hashes a file identifier, taking the case sensitivity of the file system
  95          * into account. This helps mitigating problems with case-insensitive
  96          * databases.
  97          *
  98          * @param string $identifier
  99          * @return string
 100          */
 101         public function hashIdentifier($identifier);
 102
 103         /**
 104          * Returns the identifier of the root level folder of the storage.
 105          *
 106          * @return string
 107          */
 108         public function getRootLevelFolder();
 109
 110         /**
 111          * Returns the identifier of the default folder new files should be put into.
 112          *
 113          * @return string
 114          */
 115         public function getDefaultFolder();
 116
 117         /**
 118          * Returns the identifier of the folder the file resides in
 119          *
 120          * @param string $fileIdentifier
 121          * @return string
 122          */
 123         public function getParentFolderIdentifierOfIdentifier($fileIdentifier);
 124
 125         /**
 126          * Returns the public URL to a file.
 127          * Either fully qualified URL or relative to PATH_site (rawurlencoded).
 128          *
 129          * @param string $identifier
 130          * @return string
 131          */
 132         public function getPublicUrl($identifier);
 133
 134         /**
 135          * Creates a folder, within a parent folder.
 136          * If no parent folder is given, a root level folder will be created
 137          *
 138          * @param string $newFolderName
 139          * @param string $parentFolderIdentifier
 140          * @param bool $recursive
 141          * @return string the Identifier of the new folder
 142          */
 143         public function createFolder($newFolderName, $parentFolderIdentifier = '', $recursive = FALSE);
 144
 145         /**
 146          * Renames a folder in this storage.
 147          *
 148          * @param string $folderIdentifier
 149          * @param string $newName
 150          * @return array A map of old to new file identifiers of all affected resources
 151          */
 152         public function renameFolder($folderIdentifier, $newName);
 153
 154         /**
 155          * Removes a folder in filesystem.
 156          *
 157          * @param string $folderIdentifier
 158          * @param bool $deleteRecursively
 159          * @return bool
 160          */
 161         public function deleteFolder($folderIdentifier, $deleteRecursively = FALSE);
 162
 163         /**
 164          * Checks if a file exists.
 165          *
 166          * @param string $fileIdentifier
 167          * @return bool
 168          */
 169         public function fileExists($fileIdentifier);
 170
 171         /**
 172          * Checks if a folder exists.
 173          *
 174          * @param string $folderIdentifier
 175          * @return bool
 176          */
 177         public function folderExists($folderIdentifier);
 178
 179         /**
 180          * Checks if a folder contains files and (if supported) other folders.
 181          *
 182          * @param string $folderIdentifier
 183          * @return bool TRUE if there are no files and folders within $folder
 184          */
 185         public function isFolderEmpty($folderIdentifier);
 186
 187         /**
 188          * Adds a file from the local server hard disk to a given path in TYPO3s
 189          * virtual file system. This assumes that the local file exists, so no
 190          * further check is done here! After a successful the original file must
 191          * not exist anymore.
 192          *
 193          * @param string $localFilePath (within PATH_site)
 194          * @param string $targetFolderIdentifier
 195          * @param string $newFileName optional, if not given original name is used
 196          * @param bool $removeOriginal if set the original file will be removed
 197          *                                after successful operation
 198          * @return string the identifier of the new file
 199          */
 200         public function addFile($localFilePath, $targetFolderIdentifier, $newFileName = '', $removeOriginal = TRUE);
 201
 202         /**
 203          * Creates a new (empty) file and returns the identifier.
 204          *
 205          * @param string $fileName
 206          * @param string $parentFolderIdentifier
 207          * @return string
 208          */
 209         public function createFile($fileName, $parentFolderIdentifier);
 210
 211         /**
 212          * Copies a file *within* the current storage.
 213          * Note that this is only about an inner storage copy action,
 214          * where a file is just copied to another folder in the same storage.
 215          *
 216          * @param string $fileIdentifier
 217          * @param string $targetFolderIdentifier
 218          * @param string $fileName
 219          * @return string the Identifier of the new file
 220          */
 221         public function copyFileWithinStorage($fileIdentifier, $targetFolderIdentifier, $fileName);
 222
 223         /**
 224          * Renames a file in this storage.
 225          *
 226          * @param string $fileIdentifier
 227          * @param string $newName The target path (including the file name!)
 228          * @return string The identifier of the file after renaming
 229          */
 230         public function renameFile($fileIdentifier, $newName);
 231
 232         /**
 233          * Replaces a file with file in local file system.
 234          *
 235          * @param string $fileIdentifier
 236          * @param string $localFilePath
 237          * @return bool TRUE if the operation succeeded
 238          */
 239         public function replaceFile($fileIdentifier, $localFilePath);
 240
 241         /**
 242          * Removes a file from the filesystem. This does not check if the file is
 243          * still used or if it is a bad idea to delete it for some other reason
 244          * this has to be taken care of in the upper layers (e.g. the Storage)!
 245          *
 246          * @param string $fileIdentifier
 247          * @return bool TRUE if deleting the file succeeded
 248          */
 249         public function deleteFile($fileIdentifier);
 250
 251         /**
 252          * Creates a hash for a file.
 253          *
 254          * @param string $fileIdentifier
 255          * @param string $hashAlgorithm The hash algorithm to use
 256          * @return string
 257          */
 258         public function hash($fileIdentifier, $hashAlgorithm);
 259
 260
 261         /**
 262          * Moves a file *within* the current storage.
 263          * Note that this is only about an inner-storage move action,
 264          * where a file is just moved to another folder in the same storage.
 265          *
 266          * @param string $fileIdentifier
 267          * @param string $targetFolderIdentifier
 268          * @param string $newFileName
 269          * @return string
 270          */
 271         public function moveFileWithinStorage($fileIdentifier, $targetFolderIdentifier, $newFileName);
 272
 273
 274         /**
 275          * Folder equivalent to moveFileWithinStorage().
 276          *
 277          * @param string $sourceFolderIdentifier
 278          * @param string $targetFolderIdentifier
 279          * @param string $newFolderName
 280          * @return array All files which are affected, map of old => new file identifiers
 281          */
 282         public function moveFolderWithinStorage($sourceFolderIdentifier, $targetFolderIdentifier, $newFolderName);
 283
 284         /**
 285          * Folder equivalent to copyFileWithinStorage().
 286          *
 287          * @param string $sourceFolderIdentifier
 288          * @param string $targetFolderIdentifier
 289          * @param string $newFolderName
 290          * @return bool
 291          */
 292         public function copyFolderWithinStorage($sourceFolderIdentifier, $targetFolderIdentifier, $newFolderName);
 293
 294         /**
 295          * Returns the contents of a file. Beware that this requires to load the
 296          * complete file into memory and also may require fetching the file from an
 297          * external location. So this might be an expensive operation (both in terms
 298          * of processing resources and money) for large files.
 299          *
 300          * @param string $fileIdentifier
 301          * @return string The file contents
 302          */
 303         public function getFileContents($fileIdentifier);
 304
 305         /**
 306          * Sets the contents of a file to the specified value.
 307          *
 308          * @param string $fileIdentifier
 309          * @param string $contents
 310          * @return int The number of bytes written to the file
 311          */
 312         public function setFileContents($fileIdentifier, $contents);
 313
 314         /**
 315          * Checks if a file inside a folder exists
 316          *
 317          * @param string $fileName
 318          * @param string $folderIdentifier
 319          * @return bool
 320          */
 321         public function fileExistsInFolder($fileName, $folderIdentifier);
 322
 323         /**
 324          * Checks if a folder inside a folder exists.
 325          *
 326          * @param string $folderName
 327          * @param string $folderIdentifier
 328          * @return bool
 329          */
 330         public function folderExistsInFolder($folderName, $folderIdentifier);
 331
 332         /**
 333          * Returns a path to a local copy of a file for processing it. When changing the
 334          * file, you have to take care of replacing the current version yourself!
 335          *
 336          * @param string $fileIdentifier
 337          * @param bool $writable Set this to FALSE if you only need the file for read
 338          *                       operations. This might speed up things, e.g. by using
 339          *                       a cached local version. Never modify the file if you
 340          *                       have set this flag!
 341          * @return string The path to the file on the local disk
 342          */
 343         public function getFileForLocalProcessing($fileIdentifier, $writable = TRUE);
 344
 345         /**
 346          * Returns the permissions of a file/folder as an array
 347          * (keys r, w) of boolean flags
 348          *
 349          * @param string $identifier
 350          * @return array
 351          */
 352         public function getPermissions($identifier);
 353
 354         /**
 355          * Directly output the contents of the file to the output
 356          * buffer. Should not take care of header files or flushing
 357          * buffer before. Will be taken care of by the Storage.
 358          *
 359          * @param string $identifier
 360          * @return void
 361          */
 362         public function dumpFileContents($identifier);
 363
 364         /**
 365          * Checks if a given identifier is within a container, e.g. if
 366          * a file or folder is within another folder.
 367          * This can e.g. be used to check for web-mounts.
 368          *
 369          * Hint: this also needs to return TRUE if the given identifier
 370          * matches the container identifier to allow access to the root
 371          * folder of a filemount.
 372          *
 373          * @param string $folderIdentifier
 374          * @param string $identifier identifier to be checked against $folderIdentifier
 375          * @return bool TRUE if $content is within or matches $folderIdentifier
 376          */
 377         public function isWithin($folderIdentifier, $identifier);
 378
 379         /**
 380          * Returns information about a file.
 381          *
 382          * @param string $fileIdentifier
 383          * @param array $propertiesToExtract Array of properties which are be extracted
 384          *                                   If empty all will be extracted
 385          * @return array
 386          */
 387         public function getFileInfoByIdentifier($fileIdentifier, array $propertiesToExtract = array());
 388
 389         /**
 390          * Returns information about a file.
 391          *
 392          * @param string $folderIdentifier
 393          * @return array
 394          */
 395         public function getFolderInfoByIdentifier($folderIdentifier);
 396
 397         /**
 398          * Returns a list of files inside the specified path
 399          *
 400          * @param string $folderIdentifier
 401          * @param int $start
 402          * @param int $numberOfItems
 403          * @param bool $recursive
 404          * @param array $filenameFilterCallbacks callbacks for filtering the items
 405          * @param string $sort Property name used to sort the items.
 406          *                     Among them may be: '' (empty, no sorting), name,
 407          *                     fileext, size, tstamp and rw.
 408          *                     If a driver does not support the given property, it
 409          *                     should fall back to "name".
 410          * @param bool $sortRev TRUE to indicate reverse sorting (last to first)
 411          * @return array of FileIdentifiers
 412          */
 413         public function getFilesInFolder($folderIdentifier, $start = 0, $numberOfItems = 0, $recursive = FALSE, array $filenameFilterCallbacks = array(), $sort = '', $sortRev = FALSE);
 414
 415         /**
 416          * Returns a list of folders inside the specified path
 417          *
 418          * @param string $folderIdentifier
 419          * @param int $start
 420          * @param int $numberOfItems
 421          * @param bool $recursive
 422          * @param array $folderNameFilterCallbacks callbacks for filtering the items
 423          * @param string $sort Property name used to sort the items.
 424          *                     Among them may be: '' (empty, no sorting), name,
 425          *                     fileext, size, tstamp and rw.
 426          *                     If a driver does not support the given property, it
 427          *                     should fall back to "name".
 428          * @param bool $sortRev TRUE to indicate reverse sorting (last to first)
 429          * @return array of Folder Identifier
 430          */
 431         public function getFoldersInFolder($folderIdentifier, $start = 0, $numberOfItems = 0, $recursive = FALSE, array $folderNameFilterCallbacks = array(), $sort = '', $sortRev = FALSE);
 432
 433         /**
 434          * Returns the number of files inside the specified path
 435          *
 436          * @param string  $folderIdentifier
 437          * @param bool $recursive
 438          * @param array   $filenameFilterCallbacks callbacks for filtering the items
 439          * @return integer Number of files in folder
 440          */
 441         public function countFilesInFolder($folderIdentifier, $recursive = FALSE, array $filenameFilterCallbacks = array());
 442
 443         /**
 444          * Returns the number of folders inside the specified path
 445          *
 446          * @param string  $folderIdentifier
 447          * @param bool $recursive
 448          * @param array   $folderNameFilterCallbacks callbacks for filtering the items
 449          * @return integer Number of folders in folder
 450          */
 451         public function countFoldersInFolder($folderIdentifier, $recursive = FALSE, array $folderNameFilterCallbacks = array());
 452
 453 }