9 * Class for a file system (FS) based file backend.
11 * All "containers" each map to a directory under the backend's base directory.
12 * For backwards-compatibility, some container paths can be set to custom paths.
13 * The wiki ID will not be used in any custom paths, so this should be avoided.
15 * Having directories with thousands of files will diminish performance.
16 * Sharding can be accomplished by using FileRepo-style hash paths.
18 * Status messages should avoid mentioning the internal FS paths.
19 * Likewise, error suppression should be used to avoid path disclosure.
21 * @ingroup FileBackend
24 class FSFileBackend
extends FileBackend
{
25 protected $basePath; // string; directory holding the container directories
26 /** @var Array Map of container names to root paths */
27 protected $containerPaths = array(); // for custom container paths
28 protected $fileMode; // integer; file permission mode
31 * @see FileBackend::__construct()
32 * Additional $config params include:
33 * basePath : File system directory that holds containers.
34 * containerPaths : Map of container names to custom file system directories.
35 * This should only be used for backwards-compatibility.
36 * fileMode : Octal UNIX file permissions to use on files stored.
38 public function __construct( array $config ) {
39 parent
::__construct( $config );
40 if ( isset( $config['basePath'] ) ) {
41 if ( substr( $this->basePath
, -1 ) === '/' ) {
42 $this->basePath
= substr( $this->basePath
, 0, -1 ); // remove trailing slash
45 $this->basePath
= null; // none; containers must have explicit paths
47 $this->containerPaths
= (array)$config['containerPaths'];
48 foreach ( $this->containerPaths
as &$path ) {
49 if ( substr( $path, -1 ) === '/' ) {
50 $path = substr( $path, 0, -1 ); // remove trailing slash
53 $this->fileMode
= isset( $config['fileMode'] )
59 * @see FileBackend::resolveContainerPath()
61 protected function resolveContainerPath( $container, $relStoragePath ) {
62 if ( isset( $this->containerPaths
[$container] ) ||
isset( $this->basePath
) ) {
63 return $relStoragePath; // container has a root directory
69 * Given the short (unresolved) and full (resolved) name of
70 * a container, return the file system path of the container.
72 * @param $shortCont string
73 * @param $fullCont string
76 protected function containerFSRoot( $shortCont, $fullCont ) {
77 if ( isset( $this->containerPaths
[$shortCont] ) ) {
78 return $this->containerPaths
[$shortCont];
79 } elseif ( isset( $this->basePath
) ) {
80 return "{$this->basePath}/{$fullCont}";
82 return null; // no container base path defined
86 * Get the absolute file system path for a storage path
88 * @param $storagePath string Storage path
91 protected function resolveToFSPath( $storagePath ) {
92 list( $fullCont, $relPath ) = $this->resolveStoragePathReal( $storagePath );
93 if ( $relPath === null ) {
94 return null; // invalid
96 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $storagePath );
97 $fsPath = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
98 if ( $relPath != '' ) {
99 $fsPath .= "/{$relPath}";
105 * @see FileBackend::isPathUsableInternal()
107 public function isPathUsableInternal( $storagePath ) {
108 $fsPath = $this->resolveToFSPath( $storagePath );
109 if ( $fsPath === null ) {
110 return false; // invalid
112 $parentDir = dirname( $fsPath );
114 wfSuppressWarnings();
115 if ( file_exists( $fsPath ) ) {
116 $ok = is_file( $fsPath ) && is_writable( $fsPath );
118 $ok = is_dir( $parentDir ) && is_writable( $parentDir );
126 * @see FileBackend::doStoreInternal()
128 protected function doStoreInternal( array $params ) {
129 $status = Status
::newGood();
131 $dest = $this->resolveToFSPath( $params['dst'] );
132 if ( $dest === null ) {
133 $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
137 if ( file_exists( $dest ) ) {
138 if ( !empty( $params['overwrite'] ) ) {
139 wfSuppressWarnings();
140 $ok = unlink( $dest );
143 $status->fatal( 'backend-fail-delete', $params['dst'] );
147 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
152 wfSuppressWarnings();
153 $ok = copy( $params['src'], $dest );
156 $status->fatal( 'backend-fail-store', $params['src'], $params['dst'] );
160 $this->chmod( $dest );
166 * @see FileBackend::doCopyInternal()
168 protected function doCopyInternal( array $params ) {
169 $status = Status
::newGood();
171 $source = $this->resolveToFSPath( $params['src'] );
172 if ( $source === null ) {
173 $status->fatal( 'backend-fail-invalidpath', $params['src'] );
177 $dest = $this->resolveToFSPath( $params['dst'] );
178 if ( $dest === null ) {
179 $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
183 if ( file_exists( $dest ) ) {
184 if ( !empty( $params['overwrite'] ) ) {
185 wfSuppressWarnings();
186 $ok = unlink( $dest );
189 $status->fatal( 'backend-fail-delete', $params['dst'] );
193 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
198 wfSuppressWarnings();
199 $ok = copy( $source, $dest );
202 $status->fatal( 'backend-fail-copy', $params['src'], $params['dst'] );
206 $this->chmod( $dest );
212 * @see FileBackend::doMoveInternal()
214 protected function doMoveInternal( array $params ) {
215 $status = Status
::newGood();
217 $source = $this->resolveToFSPath( $params['src'] );
218 if ( $source === null ) {
219 $status->fatal( 'backend-fail-invalidpath', $params['src'] );
223 $dest = $this->resolveToFSPath( $params['dst'] );
224 if ( $dest === null ) {
225 $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
229 if ( file_exists( $dest ) ) {
230 if ( !empty( $params['overwrite'] ) ) {
231 // Windows does not support moving over existing files
232 if ( wfIsWindows() ) {
233 wfSuppressWarnings();
234 $ok = unlink( $dest );
237 $status->fatal( 'backend-fail-delete', $params['dst'] );
242 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
247 wfSuppressWarnings();
248 $ok = rename( $source, $dest );
249 clearstatcache(); // file no longer at source
252 $status->fatal( 'backend-fail-move', $params['src'], $params['dst'] );
260 * @see FileBackend::doDeleteInternal()
262 protected function doDeleteInternal( array $params ) {
263 $status = Status
::newGood();
265 $source = $this->resolveToFSPath( $params['src'] );
266 if ( $source === null ) {
267 $status->fatal( 'backend-fail-invalidpath', $params['src'] );
271 if ( !is_file( $source ) ) {
272 if ( empty( $params['ignoreMissingSource'] ) ) {
273 $status->fatal( 'backend-fail-delete', $params['src'] );
275 return $status; // do nothing; either OK or bad status
278 wfSuppressWarnings();
279 $ok = unlink( $source );
282 $status->fatal( 'backend-fail-delete', $params['src'] );
290 * @see FileBackend::doCreateInternal()
292 protected function doCreateInternal( array $params ) {
293 $status = Status
::newGood();
295 $dest = $this->resolveToFSPath( $params['dst'] );
296 if ( $dest === null ) {
297 $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
301 if ( file_exists( $dest ) ) {
302 if ( !empty( $params['overwrite'] ) ) {
303 wfSuppressWarnings();
304 $ok = unlink( $dest );
307 $status->fatal( 'backend-fail-delete', $params['dst'] );
311 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
316 wfSuppressWarnings();
317 $ok = file_put_contents( $dest, $params['content'] );
320 $status->fatal( 'backend-fail-create', $params['dst'] );
324 $this->chmod( $dest );
330 * @see FileBackend::doPrepareInternal()
332 protected function doPrepareInternal( $fullCont, $dirRel, array $params ) {
333 $status = Status
::newGood();
334 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $params['dir'] );
335 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
336 $dir = ( $dirRel != '' ) ?
"{$contRoot}/{$dirRel}" : $contRoot;
337 if ( !wfMkdirParents( $dir ) ) { // make directory and its parents
338 $status->fatal( 'directorycreateerror', $params['dir'] );
339 } elseif ( !is_writable( $dir ) ) {
340 $status->fatal( 'directoryreadonlyerror', $params['dir'] );
341 } elseif ( !is_readable( $dir ) ) {
342 $status->fatal( 'directorynotreadableerror', $params['dir'] );
348 * @see FileBackend::doSecureInternal()
350 protected function doSecureInternal( $fullCont, $dirRel, array $params ) {
351 $status = Status
::newGood();
352 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $params['dir'] );
353 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
354 $dir = ( $dirRel != '' ) ?
"{$contRoot}/{$dirRel}" : $contRoot;
355 // Seed new directories with a blank index.html, to prevent crawling...
356 if ( !empty( $params['noListing'] ) && !file_exists( "{$dir}/index.html" ) ) {
357 wfSuppressWarnings();
358 $ok = file_put_contents( "{$dir}/index.html", '' );
361 $status->fatal( 'backend-fail-create', $params['dir'] . '/index.html' );
365 // Add a .htaccess file to the root of the container...
366 if ( !empty( $params['noAccess'] ) ) {
367 if ( !file_exists( "{$contRoot}/.htaccess" ) ) {
368 wfSuppressWarnings();
369 $ok = file_put_contents( "{$contRoot}/.htaccess", "Deny from all\n" );
372 $storeDir = "mwstore://{$this->name}/{$shortCont}";
373 $status->fatal( 'backend-fail-create', "{$storeDir}/.htaccess" );
382 * @see FileBackend::doCleanInternal()
384 protected function doCleanInternal( $fullCont, $dirRel, array $params ) {
385 $status = Status
::newGood();
386 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $params['dir'] );
387 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
388 $dir = ( $dirRel != '' ) ?
"{$contRoot}/{$dirRel}" : $contRoot;
389 wfSuppressWarnings();
390 if ( is_dir( $dir ) ) {
391 rmdir( $dir ); // remove directory if empty
398 * @see FileBackend::doFileExists()
400 protected function doGetFileStat( array $params ) {
401 $source = $this->resolveToFSPath( $params['src'] );
402 if ( $source === null ) {
403 return false; // invalid storage path
406 $this->trapWarnings();
407 $stat = is_file( $source ) ?
stat( $source ) : false; // regular files only
408 $hadError = $this->untrapWarnings();
412 'mtime' => wfTimestamp( TS_MW
, $stat['mtime'] ),
413 'size' => $stat['size']
415 } elseif ( !$hadError ) {
416 return false; // file does not exist
418 return null; // failure
423 * @see FileBackend::doClearCache()
425 protected function doClearCache( array $paths = null ) {
426 clearstatcache(); // clear the PHP file stat cache
430 * @see FileBackend::getFileListInternal()
432 public function getFileListInternal( $fullCont, $dirRel, array $params ) {
433 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $params['dir'] );
434 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
435 $dir = ( $dirRel != '' ) ?
"{$contRoot}/{$dirRel}" : $contRoot;
436 wfSuppressWarnings();
437 $exists = is_dir( $dir );
440 return array(); // nothing under this dir
442 wfSuppressWarnings();
443 $readable = is_readable( $dir );
446 return null; // bad permissions?
448 return new FSFileBackendFileList( $dir );
452 * @see FileBackend::getLocalReference()
454 public function getLocalReference( array $params ) {
455 $source = $this->resolveToFSPath( $params['src'] );
456 if ( $source === null ) {
459 return new FSFile( $source );
463 * @see FileBackend::getLocalCopy()
465 public function getLocalCopy( array $params ) {
466 $source = $this->resolveToFSPath( $params['src'] );
467 if ( $source === null ) {
471 // Create a new temporary file with the same extension...
472 $ext = FileBackend
::extensionFromPath( $params['src'] );
473 $tmpFile = TempFSFile
::factory( wfBaseName( $source ) . '_', $ext );
477 $tmpPath = $tmpFile->getPath();
479 // Copy the source file over the temp file
480 wfSuppressWarnings();
481 $ok = copy( $source, $tmpPath );
487 $this->chmod( $tmpPath );
493 * Chmod a file, suppressing the warnings
495 * @param $path string Absolute file system path
496 * @return bool Success
498 protected function chmod( $path ) {
499 wfSuppressWarnings();
500 $ok = chmod( $path, $this->fileMode
);
507 * Suppress E_WARNING errors and track whether any happen
511 protected function trapWarnings() {
512 $this->hadWarningErrors
[] = false; // push to stack
513 set_error_handler( array( $this, 'handleWarning' ), E_WARNING
);
517 * Unsuppress E_WARNING errors and return true if any happened
521 protected function untrapWarnings() {
522 restore_error_handler(); // restore previous handler
523 return array_pop( $this->hadWarningErrors
); // pop from stack
526 private function handleWarning() {
527 $this->hadWarningErrors
[count( $this->hadWarningErrors
) - 1] = true;
528 return true; // suppress from PHP handler
533 * Wrapper around RecursiveDirectoryIterator that catches
534 * exception or does any custom behavoir that we may want.
535 * Do not use this class from places outside FSFileBackend.
537 * @ingroup FileBackend
539 class FSFileBackendFileList
implements Iterator
{
540 /** @var RecursiveIteratorIterator */
542 protected $suffixStart; // integer
545 * @param $dir string file system directory
547 public function __construct( $dir ) {
548 $dir = realpath( $dir ); // normalize
549 $this->suffixStart
= strlen( $dir ) +
1; // size of "path/to/dir/"
551 $flags = FilesystemIterator
::CURRENT_AS_FILEINFO | FilesystemIterator
::SKIP_DOTS
;
552 $this->iter
= new RecursiveIteratorIterator(
553 new RecursiveDirectoryIterator( $dir, $flags ) );
554 } catch ( UnexpectedValueException
$e ) {
555 $this->iter
= null; // bad permissions? deleted?
559 public function current() {
560 // Return only the relative path and normalize slashes to FileBackend-style
561 // Make sure to use the realpath since the suffix is based upon that
562 return str_replace( '\\', '/',
563 substr( realpath( $this->iter
->current() ), $this->suffixStart
) );
566 public function key() {
567 return $this->iter
->key();
570 public function next() {
573 } catch ( UnexpectedValueException
$e ) {
578 public function rewind() {
580 $this->iter
->rewind();
581 } catch ( UnexpectedValueException
$e ) {
586 public function valid() {
587 return $this->iter
&& $this->iter
->valid();