includes/filerepo/backend/FSFileBackend.php

   1 <?php
   2 /**
   3  * @file
   4  * @ingroup FileBackend
   5  * @author Aaron Schulz
   6  */
   7
   8 /**
   9  * Class for a file system (FS) based file backend.
  10  *
  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.
  14  *
  15  * Having directories with thousands of files will diminish performance.
  16  * Sharding can be accomplished by using FileRepo-style hash paths.
  17  *
  18  * Status messages should avoid mentioning the internal FS paths.
  19  * Likewise, error suppression should be used to avoid path disclosure.
  20  *
  21  * @ingroup FileBackend
  22  * @since 1.19
  23  */
  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
  29
  30         protected $hadWarningErrors = array();
  31
  32         /**
  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.
  39          */
  40         public function __construct( array $config ) {
  41                 parent::__construct( $config );
  42
  43                 // Remove any possible trailing slash from directories
  44
  45                 if ( isset( $config['basePath'] ) ) {
  46                         $this->basePath = rtrim( $config['basePath'], '/' ); // remove trailing slash
  47                 } else {
  48                         $this->basePath = null; // none; containers must have explicit paths
  49                 }
  50
  51                 if( isset( $config['containerPaths'] ) ) {
  52                         $this->containerPaths = (array)$config['containerPaths'];
  53                         foreach ( $this->containerPaths as &$path ) {
  54                                 $path = rtrim( $path, '/' );  // remove trailing slash
  55                         }
  56                 }
  57
  58                 $this->fileMode = isset( $config['fileMode'] )
  59                         ? $config['fileMode']
  60                         : 0644;
  61         }
  62
  63         /**
  64          * @see FileBackendStore::resolveContainerPath()
  65          */
  66         protected function resolveContainerPath( $container, $relStoragePath ) {
  67                 // Check that container has a root directory
  68                 if ( isset( $this->containerPaths[$container] ) || isset( $this->basePath ) ) {
  69                         // Check for sane relative paths (assume the base paths are OK)
  70                         if ( $this->isLegalRelPath( $relStoragePath ) ) {
  71                                 return $relStoragePath;
  72                         }
  73                 }
  74                 return null;
  75         }
  76
  77         /**
  78          * Sanity check a relative file system path for validity
  79          *
  80          * @param $path string Normalized relative path
  81          */
  82         protected function isLegalRelPath( $path ) {
  83                 // Check for file names longer than 255 chars
  84                 if ( preg_match( '![^/]{256}!', $path ) ) { // ext3/NTFS
  85                         return false;
  86                 }
  87                 if ( wfIsWindows() ) { // NTFS
  88                         return !preg_match( '![:*?"<>]!', $path );
  89                 } else {
  90                         return true;
  91                 }
  92         }
  93
  94         /**
  95          * Given the short (unresolved) and full (resolved) name of
  96          * a container, return the file system path of the container.
  97          *
  98          * @param $shortCont string
  99          * @param $fullCont string
 100          * @return string|null
 101          */
 102         protected function containerFSRoot( $shortCont, $fullCont ) {
 103                 if ( isset( $this->containerPaths[$shortCont] ) ) {
 104                         return $this->containerPaths[$shortCont];
 105                 } elseif ( isset( $this->basePath ) ) {
 106                         return "{$this->basePath}/{$fullCont}";
 107                 }
 108                 return null; // no container base path defined
 109         }
 110
 111         /**
 112          * Get the absolute file system path for a storage path
 113          *
 114          * @param $storagePath string Storage path
 115          * @return string|null
 116          */
 117         protected function resolveToFSPath( $storagePath ) {
 118                 list( $fullCont, $relPath ) = $this->resolveStoragePathReal( $storagePath );
 119                 if ( $relPath === null ) {
 120                         return null; // invalid
 121                 }
 122                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $storagePath );
 123                 $fsPath = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 124                 if ( $relPath != '' ) {
 125                         $fsPath .= "/{$relPath}";
 126                 }
 127                 return $fsPath;
 128         }
 129
 130         /**
 131          * @see FileBackendStore::isPathUsableInternal()
 132          */
 133         public function isPathUsableInternal( $storagePath ) {
 134                 $fsPath = $this->resolveToFSPath( $storagePath );
 135                 if ( $fsPath === null ) {
 136                         return false; // invalid
 137                 }
 138                 $parentDir = dirname( $fsPath );
 139
 140                 wfSuppressWarnings();
 141                 if ( file_exists( $fsPath ) ) {
 142                         $ok = is_file( $fsPath ) && is_writable( $fsPath );
 143                 } else {
 144                         $ok = is_dir( $parentDir ) && is_writable( $parentDir );
 145                 }
 146                 wfRestoreWarnings();
 147
 148                 return $ok;
 149         }
 150
 151         /**
 152          * @see FileBackendStore::doStoreInternal()
 153          */
 154         protected function doStoreInternal( array $params ) {
 155                 $status = Status::newGood();
 156
 157                 $dest = $this->resolveToFSPath( $params['dst'] );
 158                 if ( $dest === null ) {
 159                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 160                         return $status;
 161                 }
 162
 163                 if ( file_exists( $dest ) ) {
 164                         if ( !empty( $params['overwrite'] ) ) {
 165                                 wfSuppressWarnings();
 166                                 $ok = unlink( $dest );
 167                                 wfRestoreWarnings();
 168                                 if ( !$ok ) {
 169                                         $status->fatal( 'backend-fail-delete', $params['dst'] );
 170                                         return $status;
 171                                 }
 172                         } else {
 173                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 174                                 return $status;
 175                         }
 176                 }
 177
 178                 wfSuppressWarnings();
 179                 $ok = copy( $params['src'], $dest );
 180                 wfRestoreWarnings();
 181                 if ( !$ok ) {
 182                         $status->fatal( 'backend-fail-store', $params['src'], $params['dst'] );
 183                         return $status;
 184                 }
 185
 186                 $this->chmod( $dest );
 187
 188                 return $status;
 189         }
 190
 191         /**
 192          * @see FileBackendStore::doCopyInternal()
 193          */
 194         protected function doCopyInternal( array $params ) {
 195                 $status = Status::newGood();
 196
 197                 $source = $this->resolveToFSPath( $params['src'] );
 198                 if ( $source === null ) {
 199                         $status->fatal( 'backend-fail-invalidpath', $params['src'] );
 200                         return $status;
 201                 }
 202
 203                 $dest = $this->resolveToFSPath( $params['dst'] );
 204                 if ( $dest === null ) {
 205                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 206                         return $status;
 207                 }
 208
 209                 if ( file_exists( $dest ) ) {
 210                         if ( !empty( $params['overwrite'] ) ) {
 211                                 wfSuppressWarnings();
 212                                 $ok = unlink( $dest );
 213                                 wfRestoreWarnings();
 214                                 if ( !$ok ) {
 215                                         $status->fatal( 'backend-fail-delete', $params['dst'] );
 216                                         return $status;
 217                                 }
 218                         } else {
 219                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 220                                 return $status;
 221                         }
 222                 }
 223
 224                 wfSuppressWarnings();
 225                 $ok = copy( $source, $dest );
 226                 wfRestoreWarnings();
 227                 if ( !$ok ) {
 228                         $status->fatal( 'backend-fail-copy', $params['src'], $params['dst'] );
 229                         return $status;
 230                 }
 231
 232                 $this->chmod( $dest );
 233
 234                 return $status;
 235         }
 236
 237         /**
 238          * @see FileBackendStore::doMoveInternal()
 239          */
 240         protected function doMoveInternal( array $params ) {
 241                 $status = Status::newGood();
 242
 243                 $source = $this->resolveToFSPath( $params['src'] );
 244                 if ( $source === null ) {
 245                         $status->fatal( 'backend-fail-invalidpath', $params['src'] );
 246                         return $status;
 247                 }
 248
 249                 $dest = $this->resolveToFSPath( $params['dst'] );
 250                 if ( $dest === null ) {
 251                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 252                         return $status;
 253                 }
 254
 255                 if ( file_exists( $dest ) ) {
 256                         if ( !empty( $params['overwrite'] ) ) {
 257                                 // Windows does not support moving over existing files
 258                                 if ( wfIsWindows() ) {
 259                                         wfSuppressWarnings();
 260                                         $ok = unlink( $dest );
 261                                         wfRestoreWarnings();
 262                                         if ( !$ok ) {
 263                                                 $status->fatal( 'backend-fail-delete', $params['dst'] );
 264                                                 return $status;
 265                                         }
 266                                 }
 267                         } else {
 268                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 269                                 return $status;
 270                         }
 271                 }
 272
 273                 wfSuppressWarnings();
 274                 $ok = rename( $source, $dest );
 275                 clearstatcache(); // file no longer at source
 276                 wfRestoreWarnings();
 277                 if ( !$ok ) {
 278                         $status->fatal( 'backend-fail-move', $params['src'], $params['dst'] );
 279                         return $status;
 280                 }
 281
 282                 return $status;
 283         }
 284
 285         /**
 286          * @see FileBackendStore::doDeleteInternal()
 287          */
 288         protected function doDeleteInternal( array $params ) {
 289                 $status = Status::newGood();
 290
 291                 $source = $this->resolveToFSPath( $params['src'] );
 292                 if ( $source === null ) {
 293                         $status->fatal( 'backend-fail-invalidpath', $params['src'] );
 294                         return $status;
 295                 }
 296
 297                 if ( !is_file( $source ) ) {
 298                         if ( empty( $params['ignoreMissingSource'] ) ) {
 299                                 $status->fatal( 'backend-fail-delete', $params['src'] );
 300                         }
 301                         return $status; // do nothing; either OK or bad status
 302                 }
 303
 304                 wfSuppressWarnings();
 305                 $ok = unlink( $source );
 306                 wfRestoreWarnings();
 307                 if ( !$ok ) {
 308                         $status->fatal( 'backend-fail-delete', $params['src'] );
 309                         return $status;
 310                 }
 311
 312                 return $status;
 313         }
 314
 315         /**
 316          * @see FileBackendStore::doCreateInternal()
 317          */
 318         protected function doCreateInternal( array $params ) {
 319                 $status = Status::newGood();
 320
 321                 $dest = $this->resolveToFSPath( $params['dst'] );
 322                 if ( $dest === null ) {
 323                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 324                         return $status;
 325                 }
 326
 327                 if ( file_exists( $dest ) ) {
 328                         if ( !empty( $params['overwrite'] ) ) {
 329                                 wfSuppressWarnings();
 330                                 $ok = unlink( $dest );
 331                                 wfRestoreWarnings();
 332                                 if ( !$ok ) {
 333                                         $status->fatal( 'backend-fail-delete', $params['dst'] );
 334                                         return $status;
 335                                 }
 336                         } else {
 337                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 338                                 return $status;
 339                         }
 340                 }
 341
 342                 wfSuppressWarnings();
 343                 $bytes = file_put_contents( $dest, $params['content'] );
 344                 wfRestoreWarnings();
 345                 if ( $bytes === false ) {
 346                         $status->fatal( 'backend-fail-create', $params['dst'] );
 347                         return $status;
 348                 }
 349
 350                 $this->chmod( $dest );
 351
 352                 return $status;
 353         }
 354
 355         /**
 356          * @see FileBackendStore::doPrepareInternal()
 357          */
 358         protected function doPrepareInternal( $fullCont, $dirRel, array $params ) {
 359                 $status = Status::newGood();
 360                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 361                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 362                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 363                 if ( !wfMkdirParents( $dir ) ) { // make directory and its parents
 364                         $status->fatal( 'directorycreateerror', $params['dir'] );
 365                 } elseif ( !is_writable( $dir ) ) {
 366                         $status->fatal( 'directoryreadonlyerror', $params['dir'] );
 367                 } elseif ( !is_readable( $dir ) ) {
 368                         $status->fatal( 'directorynotreadableerror', $params['dir'] );
 369                 }
 370                 return $status;
 371         }
 372
 373         /**
 374          * @see FileBackendStore::doSecureInternal()
 375          */
 376         protected function doSecureInternal( $fullCont, $dirRel, array $params ) {
 377                 $status = Status::newGood();
 378                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 379                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 380                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 381                 // Seed new directories with a blank index.html, to prevent crawling...
 382                 if ( !empty( $params['noListing'] ) && !file_exists( "{$dir}/index.html" ) ) {
 383                         wfSuppressWarnings();
 384                         $bytes = file_put_contents( "{$dir}/index.html", '' );
 385                         wfRestoreWarnings();
 386                         if ( !$bytes ) {
 387                                 $status->fatal( 'backend-fail-create', $params['dir'] . '/index.html' );
 388                                 return $status;
 389                         }
 390                 }
 391                 // Add a .htaccess file to the root of the container...
 392                 if ( !empty( $params['noAccess'] ) ) {
 393                         if ( !file_exists( "{$contRoot}/.htaccess" ) ) {
 394                                 wfSuppressWarnings();
 395                                 $bytes = file_put_contents( "{$contRoot}/.htaccess", "Deny from all\n" );
 396                                 wfRestoreWarnings();
 397                                 if ( !$bytes ) {
 398                                         $storeDir = "mwstore://{$this->name}/{$shortCont}";
 399                                         $status->fatal( 'backend-fail-create', "{$storeDir}/.htaccess" );
 400                                         return $status;
 401                                 }
 402                         }
 403                 }
 404                 return $status;
 405         }
 406
 407         /**
 408          * @see FileBackendStore::doCleanInternal()
 409          */
 410         protected function doCleanInternal( $fullCont, $dirRel, array $params ) {
 411                 $status = Status::newGood();
 412                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 413                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 414                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 415                 wfSuppressWarnings();
 416                 if ( is_dir( $dir ) ) {
 417                         rmdir( $dir ); // remove directory if empty
 418                 }
 419                 wfRestoreWarnings();
 420                 return $status;
 421         }
 422
 423         /**
 424          * @see FileBackendStore::doFileExists()
 425          */
 426         protected function doGetFileStat( array $params ) {
 427                 $source = $this->resolveToFSPath( $params['src'] );
 428                 if ( $source === null ) {
 429                         return false; // invalid storage path
 430                 }
 431
 432                 $this->trapWarnings();
 433                 $stat = is_file( $source ) ? stat( $source ) : false; // regular files only
 434                 $hadError = $this->untrapWarnings();
 435
 436                 if ( $stat ) {
 437                         return array(
 438                                 'mtime' => wfTimestamp( TS_MW, $stat['mtime'] ),
 439                                 'size'  => $stat['size']
 440                         );
 441                 } elseif ( !$hadError ) {
 442                         return false; // file does not exist
 443                 } else {
 444                         return null; // failure
 445                 }
 446         }
 447
 448         /**
 449          * @see FileBackendStore::doClearCache()
 450          */
 451         protected function doClearCache( array $paths = null ) {
 452                 clearstatcache(); // clear the PHP file stat cache
 453         }
 454
 455         /**
 456          * @see FileBackendStore::getFileListInternal()
 457          */
 458         public function getFileListInternal( $fullCont, $dirRel, array $params ) {
 459                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 460                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 461                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 462                 wfSuppressWarnings();
 463                 $exists = is_dir( $dir );
 464                 wfRestoreWarnings();
 465                 if ( !$exists ) {
 466                         wfDebug( __METHOD__ . "() given directory does not exist: '$dir'\n" );
 467                         return array(); // nothing under this dir
 468                 }
 469                 wfSuppressWarnings();
 470                 $readable = is_readable( $dir );
 471                 wfRestoreWarnings();
 472                 if ( !$readable ) {
 473                         wfDebug( __METHOD__ . "() given directory is unreadable: '$dir'\n" );
 474                         return null; // bad permissions?
 475                 }
 476                 return new FSFileBackendFileList( $dir );
 477         }
 478
 479         /**
 480          * @see FileBackendStore::getLocalReference()
 481          */
 482         public function getLocalReference( array $params ) {
 483                 $source = $this->resolveToFSPath( $params['src'] );
 484                 if ( $source === null ) {
 485                         return null;
 486                 }
 487                 return new FSFile( $source );
 488         }
 489
 490         /**
 491          * @see FileBackendStore::getLocalCopy()
 492          */
 493         public function getLocalCopy( array $params ) {
 494                 $source = $this->resolveToFSPath( $params['src'] );
 495                 if ( $source === null ) {
 496                         return null;
 497                 }
 498
 499                 // Create a new temporary file with the same extension...
 500                 $ext = FileBackend::extensionFromPath( $params['src'] );
 501                 $tmpFile = TempFSFile::factory( wfBaseName( $source ) . '_', $ext );
 502                 if ( !$tmpFile ) {
 503                         return null;
 504                 }
 505                 $tmpPath = $tmpFile->getPath();
 506
 507                 // Copy the source file over the temp file
 508                 wfSuppressWarnings();
 509                 $ok = copy( $source, $tmpPath );
 510                 wfRestoreWarnings();
 511                 if ( !$ok ) {
 512                         return null;
 513                 }
 514
 515                 $this->chmod( $tmpPath );
 516
 517                 return $tmpFile;
 518         }
 519
 520         /**
 521          * Chmod a file, suppressing the warnings
 522          *
 523          * @param $path string Absolute file system path
 524          * @return bool Success
 525          */
 526         protected function chmod( $path ) {
 527                 wfSuppressWarnings();
 528                 $ok = chmod( $path, $this->fileMode );
 529                 wfRestoreWarnings();
 530
 531                 return $ok;
 532         }
 533
 534         /**
 535          * Suppress E_WARNING errors and track whether any happen
 536          *
 537          * @return void
 538          */
 539         protected function trapWarnings() {
 540                 $this->hadWarningErrors[] = false; // push to stack
 541                 set_error_handler( array( $this, 'handleWarning' ), E_WARNING );
 542         }
 543
 544         /**
 545          * Unsuppress E_WARNING errors and return true if any happened
 546          *
 547          * @return bool
 548          */
 549         protected function untrapWarnings() {
 550                 restore_error_handler(); // restore previous handler
 551                 return array_pop( $this->hadWarningErrors ); // pop from stack
 552         }
 553
 554         private function handleWarning() {
 555                 $this->hadWarningErrors[count( $this->hadWarningErrors ) - 1] = true;
 556                 return true; // suppress from PHP handler
 557         }
 558 }
 559
 560 /**
 561  * Wrapper around RecursiveDirectoryIterator that catches
 562  * exception or does any custom behavoir that we may want.
 563  * Do not use this class from places outside FSFileBackend.
 564  *
 565  * @ingroup FileBackend
 566  */
 567 class FSFileBackendFileList implements Iterator {
 568         /** @var RecursiveIteratorIterator */
 569         protected $iter;
 570         protected $suffixStart; // integer
 571         protected $pos = 0; // integer
 572
 573         /**
 574          * @param $dir string file system directory
 575          */
 576         public function __construct( $dir ) {
 577                 $dir = realpath( $dir ); // normalize
 578                 $this->suffixStart = strlen( $dir ) + 1; // size of "path/to/dir/"
 579                 try {
 580                         # Get an iterator that will return leaf nodes (non-directories)
 581                         if ( MWInit::classExists( 'FilesystemIterator' ) ) { // PHP >= 5.3
 582                                 # RecursiveDirectoryIterator extends FilesystemIterator.
 583                                 # FilesystemIterator::SKIP_DOTS default is inconsistent in PHP 5.3.x.
 584                                 $flags = FilesystemIterator::CURRENT_AS_FILEINFO | FilesystemIterator::SKIP_DOTS;
 585                                 $this->iter = new RecursiveIteratorIterator(
 586                                         new RecursiveDirectoryIterator( $dir, $flags ) );
 587                         } else { // PHP < 5.3
 588                                 # RecursiveDirectoryIterator extends DirectoryIterator
 589                                 $this->iter = new RecursiveIteratorIterator(
 590                                         new RecursiveDirectoryIterator( $dir ) );
 591                         }
 592                 } catch ( UnexpectedValueException $e ) {
 593                         $this->iter = null; // bad permissions? deleted?
 594                 }
 595         }
 596
 597         public function current() {
 598                 // Return only the relative path and normalize slashes to FileBackend-style
 599                 // Make sure to use the realpath since the suffix is based upon that
 600                 return str_replace( '\\', '/',
 601                         substr( realpath( $this->iter->current() ), $this->suffixStart ) );
 602         }
 603
 604         public function key() {
 605                 return $this->pos;
 606         }
 607
 608         public function next() {
 609                 try {
 610                         $this->iter->next();
 611                 } catch ( UnexpectedValueException $e ) {
 612                         $this->iter = null;
 613                 }
 614                 ++$this->pos;
 615         }
 616
 617         public function rewind() {
 618                 $this->pos = 0;
 619                 try {
 620                         $this->iter->rewind();
 621                 } catch ( UnexpectedValueException $e ) {
 622                         $this->iter = null;
 623                 }
 624         }
 625
 626         public function valid() {
 627                 return $this->iter && $this->iter->valid();
 628         }
 629 }