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

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