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