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