[!!!][TASK] FAL: Use file drivers correctly in Folder::getSubfolder
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Classes / Resource / Driver / DriverInterface.php
index bd5698a..e310359 100644 (file)
@@ -1,31 +1,18 @@
 <?php
 namespace TYPO3\CMS\Core\Resource\Driver;
 
-/***************************************************************
- * Copyright notice
+/*
+ * This file is part of the TYPO3 CMS project.
  *
- * (c) 2013 Steffen Ritter <steffen.ritter@typo3.org>
- * All rights reserved
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
  *
- * This script is part of the TYPO3 project. The TYPO3 project is
- * free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
  *
- * The GNU General Public License can be found at
- * http://www.gnu.org/copyleft/gpl.html.
- * A copy is found in the text file GPL.txt and important notices to the license
- * from the author is found in LICENSE.txt distributed with these scripts.
- *
- *
- * This script is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * This copyright notice MUST APPEAR in all copies of the script!
- ***************************************************************/
+ * The TYPO3 project - inspiring people to share!
+ */
 
 
 /**
@@ -43,7 +30,7 @@ interface DriverInterface {
        /**
         * Sets the storage uid the driver belongs to
         *
-        * @param integer $storageUid
+        * @param int $storageUid
         * @return void
         */
        public function setStorageUid($storageUid);
@@ -59,16 +46,26 @@ interface DriverInterface {
        /**
         * Returns the capabilities of this driver.
         *
-        * @return integer
+        * @return int
         * @see Storage::CAPABILITY_* constants
         */
        public function getCapabilities();
 
+       /**
+        * Merges the capabilities merged by the user at the storage
+        * configuration into the actual capabilities of the driver
+        * and returns the result.
+        *
+        * @param int $capabilities
+        * @return int
+        */
+       public function mergeConfigurationCapabilities($capabilities);
+
        /**
         * Returns TRUE if this driver has the given capability.
         *
-        * @param integer $capability A capability, as defined in a CAPABILITY_* constant
-        * @return boolean
+        * @param int $capability A capability, as defined in a CAPABILITY_* constant
+        * @return bool
         */
        public function hasCapability($capability);
 
@@ -79,7 +76,7 @@ interface DriverInterface {
         * therefore always reflect the file system and not try to change its
         * behaviour
         *
-        * @return boolean
+        * @return bool
         */
        public function isCaseSensitiveFileSystem();
 
@@ -121,23 +118,18 @@ interface DriverInterface {
         * Returns the identifier of the folder the file resides in
         *
         * @param string $fileIdentifier
-        *
         * @return string
         */
        public function getParentFolderIdentifierOfIdentifier($fileIdentifier);
 
        /**
         * Returns the public URL to a file.
+        * Either fully qualified URL or relative to PATH_site (rawurlencoded).
         *
         * @param string $identifier
-        * @param boolean $relativeToCurrentScript Determines whether the URL
-        *                                         returned should be relative
-        *                                         to the current script, in case
-        *                                         it is relative at all (only
-        *                                         for the LocalDriver)
         * @return string
         */
-       public function getPublicUrl($identifier, $relativeToCurrentScript = FALSE);
+       public function getPublicUrl($identifier);
 
        /**
         * Creates a folder, within a parent folder.
@@ -145,7 +137,7 @@ interface DriverInterface {
         *
         * @param string $newFolderName
         * @param string $parentFolderIdentifier
-        * @param boolean $recursive
+        * @param bool $recursive
         * @return string the Identifier of the new folder
         */
        public function createFolder($newFolderName, $parentFolderIdentifier = '', $recursive = FALSE);
@@ -163,8 +155,8 @@ interface DriverInterface {
         * Removes a folder in filesystem.
         *
         * @param string $folderIdentifier
-        * @param boolean $deleteRecursively
-        * @return boolean
+        * @param bool $deleteRecursively
+        * @return bool
         */
        public function deleteFolder($folderIdentifier, $deleteRecursively = FALSE);
 
@@ -172,8 +164,7 @@ interface DriverInterface {
         * Checks if a file exists.
         *
         * @param string $fileIdentifier
-        *
-        * @return boolean
+        * @return bool
         */
        public function fileExists($fileIdentifier);
 
@@ -181,8 +172,7 @@ interface DriverInterface {
         * Checks if a folder exists.
         *
         * @param string $folderIdentifier
-        *
-        * @return boolean
+        * @return bool
         */
        public function folderExists($folderIdentifier);
 
@@ -190,7 +180,7 @@ interface DriverInterface {
         * Checks if a folder contains files and (if supported) other folders.
         *
         * @param string $folderIdentifier
-        * @return boolean TRUE if there are no files and folders within $folder
+        * @return bool TRUE if there are no files and folders within $folder
         */
        public function isFolderEmpty($folderIdentifier);
 
@@ -203,7 +193,7 @@ interface DriverInterface {
         * @param string $localFilePath (within PATH_site)
         * @param string $targetFolderIdentifier
         * @param string $newFileName optional, if not given original name is used
-        * @param boolean $removeOriginal if set the original file will be removed
+        * @param bool $removeOriginal if set the original file will be removed
         *                                after successful operation
         * @return string the identifier of the new file
         */
@@ -244,7 +234,7 @@ interface DriverInterface {
         *
         * @param string $fileIdentifier
         * @param string $localFilePath
-        * @return boolean TRUE if the operation succeeded
+        * @return bool TRUE if the operation succeeded
         */
        public function replaceFile($fileIdentifier, $localFilePath);
 
@@ -254,7 +244,7 @@ interface DriverInterface {
         * this has to be taken care of in the upper layers (e.g. the Storage)!
         *
         * @param string $fileIdentifier
-        * @return boolean TRUE if deleting the file succeeded
+        * @return bool TRUE if deleting the file succeeded
         */
        public function deleteFile($fileIdentifier);
 
@@ -276,7 +266,6 @@ interface DriverInterface {
         * @param string $fileIdentifier
         * @param string $targetFolderIdentifier
         * @param string $newFileName
-        *
         * @return string
         */
        public function moveFileWithinStorage($fileIdentifier, $targetFolderIdentifier, $newFileName);
@@ -288,7 +277,6 @@ interface DriverInterface {
         * @param string $sourceFolderIdentifier
         * @param string $targetFolderIdentifier
         * @param string $newFolderName
-        *
         * @return array All files which are affected, map of old => new file identifiers
         */
        public function moveFolderWithinStorage($sourceFolderIdentifier, $targetFolderIdentifier, $newFolderName);
@@ -299,8 +287,7 @@ interface DriverInterface {
         * @param string $sourceFolderIdentifier
         * @param string $targetFolderIdentifier
         * @param string $newFolderName
-        *
-        * @return boolean
+        * @return bool
         */
        public function copyFolderWithinStorage($sourceFolderIdentifier, $targetFolderIdentifier, $newFolderName);
 
@@ -320,7 +307,7 @@ interface DriverInterface {
         *
         * @param string $fileIdentifier
         * @param string $contents
-        * @return integer The number of bytes written to the file
+        * @return int The number of bytes written to the file
         */
        public function setFileContents($fileIdentifier, $contents);
 
@@ -329,7 +316,7 @@ interface DriverInterface {
         *
         * @param string $fileName
         * @param string $folderIdentifier
-        * @return boolean
+        * @return bool
         */
        public function fileExistsInFolder($fileName, $folderIdentifier);
 
@@ -338,7 +325,7 @@ interface DriverInterface {
         *
         * @param string $folderName
         * @param string $folderIdentifier
-        * @return boolean
+        * @return bool
         */
        public function folderExistsInFolder($folderName, $folderIdentifier);
 
@@ -379,10 +366,13 @@ interface DriverInterface {
         * a file or folder is within another folder.
         * This can e.g. be used to check for web-mounts.
         *
+        * Hint: this also needs to return TRUE if the given identifier
+        * matches the container identifier to allow access to the root
+        * folder of a filemount.
+        *
         * @param string $folderIdentifier
         * @param string $identifier identifier to be checked against $folderIdentifier
-        *
-        * @return boolean TRUE if $content is within $folderIdentifier
+        * @return bool TRUE if $content is within or matches $folderIdentifier
         */
        public function isWithin($folderIdentifier, $identifier);
 
@@ -404,30 +394,78 @@ interface DriverInterface {
         */
        public function getFolderInfoByIdentifier($folderIdentifier);
 
+       /**
+        * Returns the identifier of a file inside the folder
+        *
+        * @param string $fileName
+        * @param string $folderIdentifier
+        * @return string file identifier
+        */
+       public function getFileInFolder($fileName, $folderIdentifier);
+
        /**
         * Returns a list of files inside the specified path
         *
         * @param string $folderIdentifier
-        * @param integer $start
-        * @param integer $numberOfItems
-        * @param boolean $recursive
+        * @param int $start
+        * @param int $numberOfItems
+        * @param bool $recursive
         * @param array $filenameFilterCallbacks callbacks for filtering the items
-        *
+        * @param string $sort Property name used to sort the items.
+        *                     Among them may be: '' (empty, no sorting), name,
+        *                     fileext, size, tstamp and rw.
+        *                     If a driver does not support the given property, it
+        *                     should fall back to "name".
+        * @param bool $sortRev TRUE to indicate reverse sorting (last to first)
         * @return array of FileIdentifiers
         */
-       public function getFilesInFolder($folderIdentifier, $start = 0, $numberOfItems = 0, $recursive = FALSE, array $filenameFilterCallbacks = array());
+       public function getFilesInFolder($folderIdentifier, $start = 0, $numberOfItems = 0, $recursive = FALSE, array $filenameFilterCallbacks = array(), $sort = '', $sortRev = FALSE);
+
+       /**
+        * Returns the identifier of a folder inside the folder
+        *
+        * @param string $folderName The name of the target folder
+        * @param string $folderIdentifier
+        * @return string folder identifier
+        */
+       public function getFolderInFolder($folderName, $folderIdentifier);
 
        /**
         * Returns a list of folders inside the specified path
         *
         * @param string $folderIdentifier
-        * @param integer $start
-        * @param integer $numberOfItems
-        * @param boolean $recursive
+        * @param int $start
+        * @param int $numberOfItems
+        * @param bool $recursive
         * @param array $folderNameFilterCallbacks callbacks for filtering the items
-        *
+        * @param string $sort Property name used to sort the items.
+        *                     Among them may be: '' (empty, no sorting), name,
+        *                     fileext, size, tstamp and rw.
+        *                     If a driver does not support the given property, it
+        *                     should fall back to "name".
+        * @param bool $sortRev TRUE to indicate reverse sorting (last to first)
         * @return array of Folder Identifier
         */
-       public function getFoldersInFolder($folderIdentifier, $start = 0, $numberOfItems = 0, $recursive = FALSE, array $folderNameFilterCallbacks = array());
+       public function getFoldersInFolder($folderIdentifier, $start = 0, $numberOfItems = 0, $recursive = FALSE, array $folderNameFilterCallbacks = array(), $sort = '', $sortRev = FALSE);
+
+       /**
+        * Returns the number of files inside the specified path
+        *
+        * @param string  $folderIdentifier
+        * @param bool $recursive
+        * @param array   $filenameFilterCallbacks callbacks for filtering the items
+        * @return integer Number of files in folder
+        */
+       public function countFilesInFolder($folderIdentifier, $recursive = FALSE, array $filenameFilterCallbacks = array());
+
+       /**
+        * Returns the number of folders inside the specified path
+        *
+        * @param string  $folderIdentifier
+        * @param bool $recursive
+        * @param array   $folderNameFilterCallbacks callbacks for filtering the items
+        * @return integer Number of folders in folder
+        */
+       public function countFoldersInFolder($folderIdentifier, $recursive = FALSE, array $folderNameFilterCallbacks = array());
 
-}
\ No newline at end of file
+}