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