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