includes/filerepo/backend/FSFileBackend.php

   1 <?php
   2 /**
   3  * @file
   4  * @ingroup FileBackend
   5  * @author Aaron Schulz
   6  */
   7
   8 /**
   9  * @brief 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  * PHP warnings are assumed to be logged rather than output.
  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                 if ( isset( $config['basePath'] ) ) {
  45                         $this->basePath = rtrim( $config['basePath'], '/' ); // remove trailing slash
  46                 } else {
  47                         $this->basePath = null; // none; containers must have explicit paths
  48                 }
  49
  50                 if ( isset( $config['containerPaths'] ) ) {
  51                         $this->containerPaths = (array)$config['containerPaths'];
  52                         foreach ( $this->containerPaths as &$path ) {
  53                                 $path = rtrim( $path, '/' );  // remove trailing slash
  54                         }
  55                 }
  56
  57                 $this->fileMode = isset( $config['fileMode'] )
  58                         ? $config['fileMode']
  59                         : 0644;
  60         }
  61
  62         /**
  63          * @see FileBackendStore::resolveContainerPath()
  64          * @return null|string
  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          * @return bool
  82          */
  83         protected function isLegalRelPath( $path ) {
  84                 // Check for file names longer than 255 chars
  85                 if ( preg_match( '![^/]{256}!', $path ) ) { // ext3/NTFS
  86                         return false;
  87                 }
  88                 if ( wfIsWindows() ) { // NTFS
  89                         return !preg_match( '![:*?"<>|]!', $path );
  90                 } else {
  91                         return true;
  92                 }
  93         }
  94
  95         /**
  96          * Given the short (unresolved) and full (resolved) name of
  97          * a container, return the file system path of the container.
  98          *
  99          * @param $shortCont string
 100          * @param $fullCont string
 101          * @return string|null
 102          */
 103         protected function containerFSRoot( $shortCont, $fullCont ) {
 104                 if ( isset( $this->containerPaths[$shortCont] ) ) {
 105                         return $this->containerPaths[$shortCont];
 106                 } elseif ( isset( $this->basePath ) ) {
 107                         return "{$this->basePath}/{$fullCont}";
 108                 }
 109                 return null; // no container base path defined
 110         }
 111
 112         /**
 113          * Get the absolute file system path for a storage path
 114          *
 115          * @param $storagePath string Storage path
 116          * @return string|null
 117          */
 118         protected function resolveToFSPath( $storagePath ) {
 119                 list( $fullCont, $relPath ) = $this->resolveStoragePathReal( $storagePath );
 120                 if ( $relPath === null ) {
 121                         return null; // invalid
 122                 }
 123                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $storagePath );
 124                 $fsPath = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 125                 if ( $relPath != '' ) {
 126                         $fsPath .= "/{$relPath}";
 127                 }
 128                 return $fsPath;
 129         }
 130
 131         /**
 132          * @see FileBackendStore::isPathUsableInternal()
 133          * @return bool
 134          */
 135         public function isPathUsableInternal( $storagePath ) {
 136                 $fsPath = $this->resolveToFSPath( $storagePath );
 137                 if ( $fsPath === null ) {
 138                         return false; // invalid
 139                 }
 140                 $parentDir = dirname( $fsPath );
 141
 142                 if ( file_exists( $fsPath ) ) {
 143                         $ok = is_file( $fsPath ) && is_writable( $fsPath );
 144                 } else {
 145                         $ok = is_dir( $parentDir ) && is_writable( $parentDir );
 146                 }
 147
 148                 return $ok;
 149         }
 150
 151         /**
 152          * @see FileBackendStore::doStoreInternal()
 153          * @return Status
 154          */
 155         protected function doStoreInternal( array $params ) {
 156                 $status = Status::newGood();
 157
 158                 $dest = $this->resolveToFSPath( $params['dst'] );
 159                 if ( $dest === null ) {
 160                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 161                         return $status;
 162                 }
 163
 164                 if ( file_exists( $dest ) ) {
 165                         if ( !empty( $params['overwrite'] ) ) {
 166                                 $ok = unlink( $dest );
 167                                 if ( !$ok ) {
 168                                         $status->fatal( 'backend-fail-delete', $params['dst'] );
 169                                         return $status;
 170                                 }
 171                         } else {
 172                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 173                                 return $status;
 174                         }
 175                 }
 176
 177                 $ok = copy( $params['src'], $dest );
 178                 // In some cases (at least over NFS), copy() returns true when it fails.
 179                 if ( !$ok || ( filesize( $params['src'] ) !== filesize( $dest ) ) ) {
 180                         if ( $ok ) { // PHP bug
 181                                 unlink( $dest ); // remove broken file
 182                                 trigger_error( __METHOD__ . ": copy() failed but returned true." );
 183                         }
 184                         $status->fatal( 'backend-fail-store', $params['src'], $params['dst'] );
 185                         return $status;
 186                 }
 187
 188                 $this->chmod( $dest );
 189
 190                 return $status;
 191         }
 192
 193         /**
 194          * @see FileBackendStore::doCopyInternal()
 195          * @return Status
 196          */
 197         protected function doCopyInternal( array $params ) {
 198                 $status = Status::newGood();
 199
 200                 $source = $this->resolveToFSPath( $params['src'] );
 201                 if ( $source === null ) {
 202                         $status->fatal( 'backend-fail-invalidpath', $params['src'] );
 203                         return $status;
 204                 }
 205
 206                 $dest = $this->resolveToFSPath( $params['dst'] );
 207                 if ( $dest === null ) {
 208                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 209                         return $status;
 210                 }
 211
 212                 if ( file_exists( $dest ) ) {
 213                         if ( !empty( $params['overwrite'] ) ) {
 214                                 $ok = unlink( $dest );
 215                                 if ( !$ok ) {
 216                                         $status->fatal( 'backend-fail-delete', $params['dst'] );
 217                                         return $status;
 218                                 }
 219                         } else {
 220                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 221                                 return $status;
 222                         }
 223                 }
 224
 225                 $ok = copy( $source, $dest );
 226                 // In some cases (at least over NFS), copy() returns true when it fails.
 227                 if ( !$ok || ( filesize( $source ) !== filesize( $dest ) ) ) {
 228                         if ( $ok ) { // PHP bug
 229                                 unlink( $dest ); // remove broken file
 230                                 trigger_error( __METHOD__ . ": copy() failed but returned true." );
 231                         }
 232                         $status->fatal( 'backend-fail-copy', $params['src'], $params['dst'] );
 233                         return $status;
 234                 }
 235
 236                 $this->chmod( $dest );
 237
 238                 return $status;
 239         }
 240
 241         /**
 242          * @see FileBackendStore::doMoveInternal()
 243          * @return Status
 244          */
 245         protected function doMoveInternal( array $params ) {
 246                 $status = Status::newGood();
 247
 248                 $source = $this->resolveToFSPath( $params['src'] );
 249                 if ( $source === null ) {
 250                         $status->fatal( 'backend-fail-invalidpath', $params['src'] );
 251                         return $status;
 252                 }
 253
 254                 $dest = $this->resolveToFSPath( $params['dst'] );
 255                 if ( $dest === null ) {
 256                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 257                         return $status;
 258                 }
 259
 260                 if ( file_exists( $dest ) ) {
 261                         if ( !empty( $params['overwrite'] ) ) {
 262                                 // Windows does not support moving over existing files
 263                                 if ( wfIsWindows() ) {
 264                                         $ok = unlink( $dest );
 265                                         if ( !$ok ) {
 266                                                 $status->fatal( 'backend-fail-delete', $params['dst'] );
 267                                                 return $status;
 268                                         }
 269                                 }
 270                         } else {
 271                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 272                                 return $status;
 273                         }
 274                 }
 275
 276                 $ok = rename( $source, $dest );
 277                 clearstatcache(); // file no longer at source
 278                 if ( !$ok ) {
 279                         $status->fatal( 'backend-fail-move', $params['src'], $params['dst'] );
 280                         return $status;
 281                 }
 282
 283                 return $status;
 284         }
 285
 286         /**
 287          * @see FileBackendStore::doDeleteInternal()
 288          * @return Status
 289          */
 290         protected function doDeleteInternal( array $params ) {
 291                 $status = Status::newGood();
 292
 293                 $source = $this->resolveToFSPath( $params['src'] );
 294                 if ( $source === null ) {
 295                         $status->fatal( 'backend-fail-invalidpath', $params['src'] );
 296                         return $status;
 297                 }
 298
 299                 if ( !is_file( $source ) ) {
 300                         if ( empty( $params['ignoreMissingSource'] ) ) {
 301                                 $status->fatal( 'backend-fail-delete', $params['src'] );
 302                         }
 303                         return $status; // do nothing; either OK or bad status
 304                 }
 305
 306                 $ok = unlink( $source );
 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          * @return Status
 318          */
 319         protected function doCreateInternal( array $params ) {
 320                 $status = Status::newGood();
 321
 322                 $dest = $this->resolveToFSPath( $params['dst'] );
 323                 if ( $dest === null ) {
 324                         $status->fatal( 'backend-fail-invalidpath', $params['dst'] );
 325                         return $status;
 326                 }
 327
 328                 if ( file_exists( $dest ) ) {
 329                         if ( !empty( $params['overwrite'] ) ) {
 330                                 $ok = unlink( $dest );
 331                                 if ( !$ok ) {
 332                                         $status->fatal( 'backend-fail-delete', $params['dst'] );
 333                                         return $status;
 334                                 }
 335                         } else {
 336                                 $status->fatal( 'backend-fail-alreadyexists', $params['dst'] );
 337                                 return $status;
 338                         }
 339                 }
 340
 341                 $bytes = file_put_contents( $dest, $params['content'] );
 342                 if ( $bytes === false ) {
 343                         $status->fatal( 'backend-fail-create', $params['dst'] );
 344                         return $status;
 345                 }
 346
 347                 $this->chmod( $dest );
 348
 349                 return $status;
 350         }
 351
 352         /**
 353          * @see FileBackendStore::doPrepareInternal()
 354          * @return Status
 355          */
 356         protected function doPrepareInternal( $fullCont, $dirRel, array $params ) {
 357                 $status = Status::newGood();
 358                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 359                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 360                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 361                 if ( !wfMkdirParents( $dir ) ) { // make directory and its parents
 362                         $status->fatal( 'directorycreateerror', $params['dir'] );
 363                 } elseif ( !is_writable( $dir ) ) {
 364                         $status->fatal( 'directoryreadonlyerror', $params['dir'] );
 365                 } elseif ( !is_readable( $dir ) ) {
 366                         $status->fatal( 'directorynotreadableerror', $params['dir'] );
 367                 }
 368                 return $status;
 369         }
 370
 371         /**
 372          * @see FileBackendStore::doSecureInternal()
 373          * @return Status
 374          */
 375         protected function doSecureInternal( $fullCont, $dirRel, array $params ) {
 376                 $status = Status::newGood();
 377                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 378                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 379                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 380                 // Seed new directories with a blank index.html, to prevent crawling...
 381                 if ( !empty( $params['noListing'] ) && !file_exists( "{$dir}/index.html" ) ) {
 382                         $bytes = file_put_contents( "{$dir}/index.html", '' );
 383                         if ( !$bytes ) {
 384                                 $status->fatal( 'backend-fail-create', $params['dir'] . '/index.html' );
 385                                 return $status;
 386                         }
 387                 }
 388                 // Add a .htaccess file to the root of the container...
 389                 if ( !empty( $params['noAccess'] ) ) {
 390                         if ( !file_exists( "{$contRoot}/.htaccess" ) ) {
 391                                 $bytes = file_put_contents( "{$contRoot}/.htaccess", "Deny from all\n" );
 392                                 if ( !$bytes ) {
 393                                         $storeDir = "mwstore://{$this->name}/{$shortCont}";
 394                                         $status->fatal( 'backend-fail-create', "{$storeDir}/.htaccess" );
 395                                         return $status;
 396                                 }
 397                         }
 398                 }
 399                 return $status;
 400         }
 401
 402         /**
 403          * @see FileBackendStore::doCleanInternal()
 404          * @return Status
 405          */
 406         protected function doCleanInternal( $fullCont, $dirRel, array $params ) {
 407                 $status = Status::newGood();
 408                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 409                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 410                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 411                 wfSuppressWarnings();
 412                 if ( is_dir( $dir ) ) {
 413                         rmdir( $dir ); // remove directory if empty
 414                 }
 415                 wfRestoreWarnings();
 416                 return $status;
 417         }
 418
 419         /**
 420          * @see FileBackendStore::doFileExists()
 421          * @return array|bool|null
 422          */
 423         protected function doGetFileStat( array $params ) {
 424                 $source = $this->resolveToFSPath( $params['src'] );
 425                 if ( $source === null ) {
 426                         return false; // invalid storage path
 427                 }
 428
 429                 $this->trapWarnings(); // don't trust 'false' if there were errors
 430                 $stat = is_file( $source ) ? stat( $source ) : false; // regular files only
 431                 $hadError = $this->untrapWarnings();
 432
 433                 if ( $stat ) {
 434                         return array(
 435                                 'mtime' => wfTimestamp( TS_MW, $stat['mtime'] ),
 436                                 'size'  => $stat['size']
 437                         );
 438                 } elseif ( !$hadError ) {
 439                         return false; // file does not exist
 440                 } else {
 441                         return null; // failure
 442                 }
 443         }
 444
 445         /**
 446          * @see FileBackendStore::doClearCache()
 447          */
 448         protected function doClearCache( array $paths = null ) {
 449                 clearstatcache(); // clear the PHP file stat cache
 450         }
 451
 452         /**
 453          * @see FileBackendStore::doDirectoryExists()
 454          * @return bool|null
 455          */
 456         protected function doDirectoryExists( $fullCont, $dirRel, array $params ) {
 457                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 458                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 459                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 460
 461                 $this->trapWarnings(); // don't trust 'false' if there were errors
 462                 $exists = is_dir( $dir );
 463                 $hadError = $this->untrapWarnings();
 464
 465                 return $hadError ? null : $exists;
 466         }
 467
 468         /**
 469          * @see FileBackendStore::getDirectoryListInternal()
 470          * @return Array|null
 471          */
 472         public function getDirectoryListInternal( $fullCont, $dirRel, array $params ) {
 473                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 474                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 475                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 476                 $exists = is_dir( $dir );
 477                 if ( !$exists ) {
 478                         wfDebug( __METHOD__ . "() given directory does not exist: '$dir'\n" );
 479                         return array(); // nothing under this dir
 480                 } elseif ( !is_readable( $dir ) ) {
 481                         wfDebug( __METHOD__ . "() given directory is unreadable: '$dir'\n" );
 482                         return null; // bad permissions?
 483                 }
 484                 return new FSFileBackendDirList( $dir, $params );
 485         }
 486
 487         /**
 488          * @see FileBackendStore::getFileListInternal()
 489          * @return array|FSFileBackendFileList|null
 490          */
 491         public function getFileListInternal( $fullCont, $dirRel, array $params ) {
 492                 list( $b, $shortCont, $r ) = FileBackend::splitStoragePath( $params['dir'] );
 493                 $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid
 494                 $dir = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot;
 495                 $exists = is_dir( $dir );
 496                 if ( !$exists ) {
 497                         wfDebug( __METHOD__ . "() given directory does not exist: '$dir'\n" );
 498                         return array(); // nothing under this dir
 499                 } elseif ( !is_readable( $dir ) ) {
 500                         wfDebug( __METHOD__ . "() given directory is unreadable: '$dir'\n" );
 501                         return null; // bad permissions?
 502                 }
 503                 return new FSFileBackendFileList( $dir, $params );
 504         }
 505
 506         /**
 507          * @see FileBackendStore::getLocalReference()
 508          * @return FSFile|null
 509          */
 510         public function getLocalReference( array $params ) {
 511                 $source = $this->resolveToFSPath( $params['src'] );
 512                 if ( $source === null ) {
 513                         return null;
 514                 }
 515                 return new FSFile( $source );
 516         }
 517
 518         /**
 519          * @see FileBackendStore::getLocalCopy()
 520          * @return null|TempFSFile
 521          */
 522         public function getLocalCopy( array $params ) {
 523                 $source = $this->resolveToFSPath( $params['src'] );
 524                 if ( $source === null ) {
 525                         return null;
 526                 }
 527
 528                 // Create a new temporary file with the same extension...
 529                 $ext = FileBackend::extensionFromPath( $params['src'] );
 530                 $tmpFile = TempFSFile::factory( wfBaseName( $source ) . '_', $ext );
 531                 if ( !$tmpFile ) {
 532                         return null;
 533                 }
 534                 $tmpPath = $tmpFile->getPath();
 535
 536                 // Copy the source file over the temp file
 537                 $ok = copy( $source, $tmpPath );
 538                 if ( !$ok ) {
 539                         return null;
 540                 }
 541
 542                 $this->chmod( $tmpPath );
 543
 544                 return $tmpFile;
 545         }
 546
 547         /**
 548          * @see FileBackendStore::directoriesAreVirtual()
 549          * @return bool
 550          */
 551         protected function directoriesAreVirtual() {
 552                 return false;
 553         }
 554
 555         /**
 556          * Chmod a file, suppressing the warnings
 557          *
 558          * @param $path string Absolute file system path
 559          * @return bool Success
 560          */
 561         protected function chmod( $path ) {
 562                 wfSuppressWarnings();
 563                 $ok = chmod( $path, $this->fileMode );
 564                 wfRestoreWarnings();
 565
 566                 return $ok;
 567         }
 568
 569         /**
 570          * Listen for E_WARNING errors and track whether any happen
 571          *
 572          * @return bool
 573          */
 574         protected function trapWarnings() {
 575                 $this->hadWarningErrors[] = false; // push to stack
 576                 set_error_handler( array( $this, 'handleWarning' ), E_WARNING );
 577                 return false; // invoke normal PHP error handler
 578         }
 579
 580         /**
 581          * Stop listening for E_WARNING errors and return true if any happened
 582          *
 583          * @return bool
 584          */
 585         protected function untrapWarnings() {
 586                 restore_error_handler(); // restore previous handler
 587                 return array_pop( $this->hadWarningErrors ); // pop from stack
 588         }
 589
 590         private function handleWarning() {
 591                 $this->hadWarningErrors[count( $this->hadWarningErrors ) - 1] = true;
 592                 return true; // suppress from PHP handler
 593         }
 594 }
 595
 596 /**
 597  * Wrapper around RecursiveDirectoryIterator/DirectoryIterator that
 598  * catches exception or does any custom behavoir that we may want.
 599  * Do not use this class from places outside FSFileBackend.
 600  *
 601  * @ingroup FileBackend
 602  */
 603 abstract class FSFileBackendList implements Iterator {
 604         /** @var Iterator */
 605         protected $iter;
 606         protected $suffixStart; // integer
 607         protected $pos = 0; // integer
 608         /** @var Array */
 609         protected $params = array();
 610
 611         /**
 612          * @param $dir string file system directory
 613          */
 614         public function __construct( $dir, array $params ) {
 615                 $dir = realpath( $dir ); // normalize
 616                 $this->suffixStart = strlen( $dir ) + 1; // size of "path/to/dir/"
 617                 $this->params = $params;
 618
 619                 try {
 620                         $this->iter = $this->initIterator( $dir );
 621                 } catch ( UnexpectedValueException $e ) {
 622                         $this->iter = null; // bad permissions? deleted?
 623                 }
 624         }
 625
 626         /**
 627          * Return an appropriate iterator object to wrap
 628          *
 629          * @param $dir string file system directory
 630          * @return Iterator
 631          */
 632         protected function initIterator( $dir ) {
 633                 if ( !empty( $this->params['topOnly'] ) ) { // non-recursive
 634                         # Get an iterator that will get direct sub-nodes
 635                         return new DirectoryIterator( $dir );
 636                 } else { // recursive
 637                         # Get an iterator that will return leaf nodes (non-directories)
 638                         if ( MWInit::classExists( 'FilesystemIterator' ) ) { // PHP >= 5.3
 639                                 # RecursiveDirectoryIterator extends FilesystemIterator.
 640                                 # FilesystemIterator::SKIP_DOTS default is inconsistent in PHP 5.3.x.
 641                                 $flags = FilesystemIterator::CURRENT_AS_SELF | FilesystemIterator::SKIP_DOTS;
 642                                 return new RecursiveIteratorIterator(
 643                                         new RecursiveDirectoryIterator( $dir, $flags ),
 644                                         RecursiveIteratorIterator::CHILD_FIRST // include dirs
 645                                 );
 646                         } else { // PHP < 5.3
 647                                 # RecursiveDirectoryIterator extends DirectoryIterator
 648                                 return new RecursiveIteratorIterator(
 649                                         new RecursiveDirectoryIterator( $dir ),
 650                                         RecursiveIteratorIterator::CHILD_FIRST // include dirs
 651                                 );
 652                         }
 653                 }
 654         }
 655
 656         /**
 657          * @see Iterator::key()
 658          * @return integer
 659          */
 660         public function key() {
 661                 return $this->pos;
 662         }
 663
 664         /**
 665          * @see Iterator::current()
 666          * @return string|bool String or false
 667          */
 668         public function current() {
 669                 return $this->getRelPath( $this->iter->current()->getPathname() );
 670         }
 671
 672         /**
 673          * @see Iterator::next()
 674          * @return void
 675          */
 676         public function next() {
 677                 try {
 678                         $this->iter->next();
 679                         $this->filterViaNext();
 680                 } catch ( UnexpectedValueException $e ) {
 681                         $this->iter = null;
 682                 }
 683                 ++$this->pos;
 684         }
 685
 686         /**
 687          * @see Iterator::rewind()
 688          * @return void
 689          */
 690         public function rewind() {
 691                 $this->pos = 0;
 692                 try {
 693                         $this->iter->rewind();
 694                         $this->filterViaNext();
 695                 } catch ( UnexpectedValueException $e ) {
 696                         $this->iter = null;
 697                 }
 698         }
 699
 700         /**
 701          * @see Iterator::valid()
 702          * @return bool
 703          */
 704         public function valid() {
 705                 return $this->iter && $this->iter->valid();
 706         }
 707
 708         /**
 709          * Filter out items by advancing to the next ones
 710          */
 711         protected function filterViaNext() {}
 712
 713         /**
 714          * Return only the relative path and normalize slashes to FileBackend-style.
 715          * Uses the "real path" since the suffix is based upon that.
 716          *
 717          * @param $path string
 718          * @return string
 719          */
 720         protected function getRelPath( $path ) {
 721                 return strtr( substr( realpath( $path ), $this->suffixStart ), '\\', '/' );
 722         }
 723 }
 724
 725 class FSFileBackendDirList extends FSFileBackendList {
 726         protected function filterViaNext() {
 727                 while ( $this->iter->valid() ) {
 728                         if ( $this->iter->current()->isDot() || !$this->iter->current()->isDir() ) {
 729                                 $this->iter->next(); // skip non-directories and dot files
 730                         } else {
 731                                 break;
 732                         }
 733                 }
 734         }
 735 }
 736
 737 class FSFileBackendFileList extends FSFileBackendList {
 738         protected function filterViaNext() {
 739                 while ( $this->iter->valid() ) {
 740                         if ( !$this->iter->current()->isFile() ) {
 741                                 $this->iter->next(); // skip non-files and dot files
 742                         } else {
 743                                 break;
 744                         }
 745                 }
 746         }
 747 }