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