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