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 FileBackendStore
{
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
30 protected $hadWarningErrors = array();
33 * @see FileBackendStore::__construct()
34 * Additional $config params include:
35 * basePath : File system directory that holds containers.
36 * containerPaths : Map of container names to custom file system directories.
37 * This should only be used for backwards-compatibility.
38 * fileMode : Octal UNIX file permissions to use on files stored.
40 public function __construct( array $config ) {
41 parent
::__construct( $config );
42 if ( isset( $config['basePath'] ) ) {
43 if ( substr( $this->basePath
, -1 ) === '/' ) {
44 $this->basePath
= substr( $this->basePath
, 0, -1 ); // remove trailing slash
47 $this->basePath
= null; // none; containers must have explicit paths
49 $this->containerPaths
= (array)$config['containerPaths'];
50 foreach ( $this->containerPaths
as &$path ) {
51 if ( substr( $path, -1 ) === '/' ) {
52 $path = substr( $path, 0, -1 ); // remove trailing slash
55 $this->fileMode
= isset( $config['fileMode'] )
61 * @see FileBackendStore::resolveContainerPath()
63 protected function resolveContainerPath( $container, $relStoragePath ) {
64 if ( isset( $this->containerPaths
[$container] ) ||
isset( $this->basePath
) ) {
65 return $relStoragePath; // container has a root directory
71 * Given the short (unresolved) and full (resolved) name of
72 * a container, return the file system path of the container.
74 * @param $shortCont string
75 * @param $fullCont string
78 protected function containerFSRoot( $shortCont, $fullCont ) {
79 if ( isset( $this->containerPaths
[$shortCont] ) ) {
80 return $this->containerPaths
[$shortCont];
81 } elseif ( isset( $this->basePath
) ) {
82 return "{$this->basePath}/{$fullCont}";
84 return null; // no container base path defined
88 * Get the absolute file system path for a storage path
90 * @param $storagePath string Storage path
93 protected function resolveToFSPath( $storagePath ) {
94 list( $fullCont, $relPath ) = $this->resolveStoragePathReal( $storagePath );
95 if ( $relPath === null ) {
96 return null; // invalid
98 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $storagePath );
99 $fsPath = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
100 if ( $relPath != '' ) {
101 $fsPath .= "/{$relPath}";
107 * @see FileBackendStore::isPathUsableInternal()
109 public function isPathUsableInternal( $storagePath ) {
110 $fsPath = $this->resolveToFSPath( $storagePath );
111 if ( $fsPath === null ) {
112 return false; // invalid
114 $parentDir = dirname( $fsPath );
116 wfSuppressWarnings();
117 if ( file_exists( $fsPath ) ) {
118 $ok = is_file( $fsPath ) && is_writable( $fsPath );
120 $ok = is_dir( $parentDir ) && is_writable( $parentDir );
128 * @see FileBackendStore::doStoreInternal()
130 protected function doStoreInternal( array $params ) {
131 $status = Status
::newGood();
133 $dest = $this->resolveToFSPath( $params['dst'] );
134 if ( $dest === null ) {
135 $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
139 if ( file_exists( $dest ) ) {
140 if ( !empty( $params['overwrite'] ) ) {
141 wfSuppressWarnings();
142 $ok = unlink( $dest );
145 $status->fatal( 'backend-fail-delete', $params['dst'] );
149 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
154 wfSuppressWarnings();
155 $ok = copy( $params['src'], $dest );
158 $status->fatal( 'backend-fail-store', $params['src'], $params['dst'] );
162 $this->chmod( $dest );
168 * @see FileBackendStore::doCopyInternal()
170 protected function doCopyInternal( array $params ) {
171 $status = Status
::newGood();
173 $source = $this->resolveToFSPath( $params['src'] );
174 if ( $source === null ) {
175 $status->fatal( 'backend-fail-invalidpath', $params['src'] );
179 $dest = $this->resolveToFSPath( $params['dst'] );
180 if ( $dest === null ) {
181 $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
185 if ( file_exists( $dest ) ) {
186 if ( !empty( $params['overwrite'] ) ) {
187 wfSuppressWarnings();
188 $ok = unlink( $dest );
191 $status->fatal( 'backend-fail-delete', $params['dst'] );
195 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
200 wfSuppressWarnings();
201 $ok = copy( $source, $dest );
204 $status->fatal( 'backend-fail-copy', $params['src'], $params['dst'] );
208 $this->chmod( $dest );
214 * @see FileBackendStore::doMoveInternal()
216 protected function doMoveInternal( array $params ) {
217 $status = Status
::newGood();
219 $source = $this->resolveToFSPath( $params['src'] );
220 if ( $source === null ) {
221 $status->fatal( 'backend-fail-invalidpath', $params['src'] );
225 $dest = $this->resolveToFSPath( $params['dst'] );
226 if ( $dest === null ) {
227 $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
231 if ( file_exists( $dest ) ) {
232 if ( !empty( $params['overwrite'] ) ) {
233 // Windows does not support moving over existing files
234 if ( wfIsWindows() ) {
235 wfSuppressWarnings();
236 $ok = unlink( $dest );
239 $status->fatal( 'backend-fail-delete', $params['dst'] );
244 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
249 wfSuppressWarnings();
250 $ok = rename( $source, $dest );
251 clearstatcache(); // file no longer at source
254 $status->fatal( 'backend-fail-move', $params['src'], $params['dst'] );
262 * @see FileBackendStore::doDeleteInternal()
264 protected function doDeleteInternal( array $params ) {
265 $status = Status
::newGood();
267 $source = $this->resolveToFSPath( $params['src'] );
268 if ( $source === null ) {
269 $status->fatal( 'backend-fail-invalidpath', $params['src'] );
273 if ( !is_file( $source ) ) {
274 if ( empty( $params['ignoreMissingSource'] ) ) {
275 $status->fatal( 'backend-fail-delete', $params['src'] );
277 return $status; // do nothing; either OK or bad status
280 wfSuppressWarnings();
281 $ok = unlink( $source );
284 $status->fatal( 'backend-fail-delete', $params['src'] );
292 * @see FileBackendStore::doCreateInternal()
294 protected function doCreateInternal( array $params ) {
295 $status = Status
::newGood();
297 $dest = $this->resolveToFSPath( $params['dst'] );
298 if ( $dest === null ) {
299 $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
303 if ( file_exists( $dest ) ) {
304 if ( !empty( $params['overwrite'] ) ) {
305 wfSuppressWarnings();
306 $ok = unlink( $dest );
309 $status->fatal( 'backend-fail-delete', $params['dst'] );
313 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
318 wfSuppressWarnings();
319 $ok = file_put_contents( $dest, $params['content'] );
322 $status->fatal( 'backend-fail-create', $params['dst'] );
326 $this->chmod( $dest );
332 * @see FileBackendStore::doPrepareInternal()
334 protected function doPrepareInternal( $fullCont, $dirRel, array $params ) {
335 $status = Status
::newGood();
336 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $params['dir'] );
337 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
338 $dir = ( $dirRel != '' ) ?
"{$contRoot}/{$dirRel}" : $contRoot;
339 if ( !wfMkdirParents( $dir ) ) { // make directory and its parents
340 $status->fatal( 'directorycreateerror', $params['dir'] );
341 } elseif ( !is_writable( $dir ) ) {
342 $status->fatal( 'directoryreadonlyerror', $params['dir'] );
343 } elseif ( !is_readable( $dir ) ) {
344 $status->fatal( 'directorynotreadableerror', $params['dir'] );
350 * @see FileBackendStore::doSecureInternal()
352 protected function doSecureInternal( $fullCont, $dirRel, array $params ) {
353 $status = Status
::newGood();
354 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $params['dir'] );
355 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
356 $dir = ( $dirRel != '' ) ?
"{$contRoot}/{$dirRel}" : $contRoot;
357 // Seed new directories with a blank index.html, to prevent crawling...
358 if ( !empty( $params['noListing'] ) && !file_exists( "{$dir}/index.html" ) ) {
359 wfSuppressWarnings();
360 $ok = file_put_contents( "{$dir}/index.html", '' );
363 $status->fatal( 'backend-fail-create', $params['dir'] . '/index.html' );
367 // Add a .htaccess file to the root of the container...
368 if ( !empty( $params['noAccess'] ) ) {
369 if ( !file_exists( "{$contRoot}/.htaccess" ) ) {
370 wfSuppressWarnings();
371 $ok = file_put_contents( "{$contRoot}/.htaccess", "Deny from all\n" );
374 $storeDir = "mwstore://{$this->name}/{$shortCont}";
375 $status->fatal( 'backend-fail-create', "{$storeDir}/.htaccess" );
384 * @see FileBackendStore::doCleanInternal()
386 protected function doCleanInternal( $fullCont, $dirRel, array $params ) {
387 $status = Status
::newGood();
388 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $params['dir'] );
389 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
390 $dir = ( $dirRel != '' ) ?
"{$contRoot}/{$dirRel}" : $contRoot;
391 wfSuppressWarnings();
392 if ( is_dir( $dir ) ) {
393 rmdir( $dir ); // remove directory if empty
400 * @see FileBackendStore::doFileExists()
402 protected function doGetFileStat( array $params ) {
403 $source = $this->resolveToFSPath( $params['src'] );
404 if ( $source === null ) {
405 return false; // invalid storage path
408 $this->trapWarnings();
409 $stat = is_file( $source ) ?
stat( $source ) : false; // regular files only
410 $hadError = $this->untrapWarnings();
414 'mtime' => wfTimestamp( TS_MW
, $stat['mtime'] ),
415 'size' => $stat['size']
417 } elseif ( !$hadError ) {
418 return false; // file does not exist
420 return null; // failure
425 * @see FileBackendStore::doClearCache()
427 protected function doClearCache( array $paths = null ) {
428 clearstatcache(); // clear the PHP file stat cache
432 * @see FileBackendStore::getFileListInternal()
434 public function getFileListInternal( $fullCont, $dirRel, array $params ) {
435 list( $b, $shortCont, $r ) = FileBackend
::splitStoragePath( $params['dir'] );
436 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
437 $dir = ( $dirRel != '' ) ?
"{$contRoot}/{$dirRel}" : $contRoot;
438 wfSuppressWarnings();
439 $exists = is_dir( $dir );
442 return array(); // nothing under this dir
444 wfSuppressWarnings();
445 $readable = is_readable( $dir );
448 return null; // bad permissions?
450 return new FSFileBackendFileList( $dir );
454 * @see FileBackendStore::getLocalReference()
456 public function getLocalReference( array $params ) {
457 $source = $this->resolveToFSPath( $params['src'] );
458 if ( $source === null ) {
461 return new FSFile( $source );
465 * @see FileBackendStore::getLocalCopy()
467 public function getLocalCopy( array $params ) {
468 $source = $this->resolveToFSPath( $params['src'] );
469 if ( $source === null ) {
473 // Create a new temporary file with the same extension...
474 $ext = FileBackend
::extensionFromPath( $params['src'] );
475 $tmpFile = TempFSFile
::factory( wfBaseName( $source ) . '_', $ext );
479 $tmpPath = $tmpFile->getPath();
481 // Copy the source file over the temp file
482 wfSuppressWarnings();
483 $ok = copy( $source, $tmpPath );
489 $this->chmod( $tmpPath );
495 * Chmod a file, suppressing the warnings
497 * @param $path string Absolute file system path
498 * @return bool Success
500 protected function chmod( $path ) {
501 wfSuppressWarnings();
502 $ok = chmod( $path, $this->fileMode
);
509 * Suppress E_WARNING errors and track whether any happen
513 protected function trapWarnings() {
514 $this->hadWarningErrors
[] = false; // push to stack
515 set_error_handler( array( $this, 'handleWarning' ), E_WARNING
);
519 * Unsuppress E_WARNING errors and return true if any happened
523 protected function untrapWarnings() {
524 restore_error_handler(); // restore previous handler
525 return array_pop( $this->hadWarningErrors
); // pop from stack
528 private function handleWarning() {
529 $this->hadWarningErrors
[count( $this->hadWarningErrors
) - 1] = true;
530 return true; // suppress from PHP handler
535 * Wrapper around RecursiveDirectoryIterator that catches
536 * exception or does any custom behavoir that we may want.
537 * Do not use this class from places outside FSFileBackend.
539 * @ingroup FileBackend
541 class FSFileBackendFileList
implements Iterator
{
542 /** @var RecursiveIteratorIterator */
544 protected $suffixStart; // integer
545 protected $pos = 0; // integer
548 * @param $dir string file system directory
550 public function __construct( $dir ) {
551 $dir = realpath( $dir ); // normalize
552 $this->suffixStart
= strlen( $dir ) +
1; // size of "path/to/dir/"
554 # Get an iterator that will return leaf nodes (non-directories)
555 if ( MWInit
::classExists( 'FilesystemIterator' ) ) { // PHP >= 5.3
556 # RecursiveDirectoryIterator extends FilesystemIterator.
557 # FilesystemIterator::SKIP_DOTS default is inconsistent in PHP 5.3.x.
558 $flags = FilesystemIterator
::CURRENT_AS_FILEINFO | FilesystemIterator
::SKIP_DOTS
;
559 $this->iter
= new RecursiveIteratorIterator(
560 new RecursiveDirectoryIterator( $dir, $flags ) );
561 } else { // PHP < 5.3
562 # RecursiveDirectoryIterator extends DirectoryIterator
563 $this->iter
= new RecursiveIteratorIterator(
564 new RecursiveDirectoryIterator( $dir ) );
566 } catch ( UnexpectedValueException
$e ) {
567 $this->iter
= null; // bad permissions? deleted?
571 public function current() {
572 // Return only the relative path and normalize slashes to FileBackend-style
573 // Make sure to use the realpath since the suffix is based upon that
574 return str_replace( '\\', '/',
575 substr( realpath( $this->iter
->current() ), $this->suffixStart
) );
578 public function key() {
582 public function next() {
585 } catch ( UnexpectedValueException
$e ) {
591 public function rewind() {
594 $this->iter
->rewind();
595 } catch ( UnexpectedValueException
$e ) {
600 public function valid() {
601 return $this->iter
&& $this->iter
->valid();