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