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