includes/filerepo/FileRepo.php

   1 <?php
   2
   3 /**
   4  * Base class for file repositories
   5  * Do not instantiate, use a derived class.
   6  * @ingroup FileRepo
   7  */
   8 abstract class FileRepo {
   9         const FILES_ONLY = 1;
  10         const DELETE_SOURCE = 1;
  11         const OVERWRITE = 2;
  12         const OVERWRITE_SAME = 4;
  13
  14         var $thumbScriptUrl, $transformVia404;
  15         var $descBaseUrl, $scriptDirUrl, $articleUrl, $fetchDescription, $initialCapital;
  16         var $pathDisclosureProtection = 'paranoid';
  17         var $descriptionCacheExpiry, $hashLevels, $url, $thumbUrl;
  18
  19         /**
  20          * Factory functions for creating new files
  21          * Override these in the base class
  22          */
  23         var $fileFactory = false, $oldFileFactory = false;
  24         var $fileFactoryKey = false, $oldFileFactoryKey = false;
  25
  26         function __construct( $info ) {
  27                 // Required settings
  28                 $this->name = $info['name'];
  29
  30                 // Optional settings
  31                 $this->initialCapital = MWNamespace::isCapitalized( NS_FILE );
  32                 foreach ( array( 'descBaseUrl', 'scriptDirUrl', 'articleUrl', 'fetchDescription',
  33                         'thumbScriptUrl', 'initialCapital', 'pathDisclosureProtection',
  34                         'descriptionCacheExpiry', 'hashLevels', 'url', 'thumbUrl' ) as $var )
  35                 {
  36                         if ( isset( $info[$var] ) ) {
  37                                 $this->$var = $info[$var];
  38                         }
  39                 }
  40                 $this->transformVia404 = !empty( $info['transformVia404'] );
  41         }
  42
  43         /**
  44          * Determine if a string is an mwrepo:// URL
  45          */
  46         static function isVirtualUrl( $url ) {
  47                 return substr( $url, 0, 9 ) == 'mwrepo://';
  48         }
  49
  50         /**
  51          * Create a new File object from the local repository
  52          * @param mixed $title Title object or string
  53          * @param mixed $time Time at which the image was uploaded.
  54          *                    If this is specified, the returned object will be an
  55          *                    instance of the repository's old file class instead of
  56          *                    a current file. Repositories not supporting version
  57          *                    control should return false if this parameter is set.
  58          */
  59         function newFile( $title, $time = false ) {
  60                 if ( !($title instanceof Title) ) {
  61                         $title = Title::makeTitleSafe( NS_FILE, $title );
  62                         if ( !is_object( $title ) ) {
  63                                 return null;
  64                         }
  65                 }
  66                 if ( $time ) {
  67                         if ( $this->oldFileFactory ) {
  68                                 return call_user_func( $this->oldFileFactory, $title, $this, $time );
  69                         } else {
  70                                 return false;
  71                         }
  72                 } else {
  73                         return call_user_func( $this->fileFactory, $title, $this );
  74                 }
  75         }
  76
  77         /**
  78          * Find an instance of the named file created at the specified time
  79          * Returns false if the file does not exist. Repositories not supporting
  80          * version control should return false if the time is specified.
  81          *
  82          * @param mixed $title Title object or string
  83          * @param $options Associative array of options:
  84          *     time:           requested time for an archived image, or false for the
  85          *                     current version. An image object will be returned which was
  86          *                     created at the specified time.
  87          *
  88          *     ignoreRedirect: If true, do not follow file redirects
  89          *
  90          *     private:        If true, return restricted (deleted) files if the current
  91          *                     user is allowed to view them. Otherwise, such files will not
  92          *                     be found.
  93          */
  94         function findFile( $title, $options = array() ) {
  95                 if ( !is_array( $options ) ) {
  96                         // MW 1.15 compat
  97                         $time = $options;
  98                 } else {
  99                         $time = isset( $options['time'] ) ? $options['time'] : false;
 100                 }
 101                 if ( !($title instanceof Title) ) {
 102                         $title = Title::makeTitleSafe( NS_FILE, $title );
 103                         if ( !is_object( $title ) ) {
 104                                 return false;
 105                         }
 106                 }
 107                 # First try the current version of the file to see if it precedes the timestamp
 108                 $img = $this->newFile( $title );
 109                 if ( !$img ) {
 110                         return false;
 111                 }
 112                 if ( $img->exists() && ( !$time || $img->getTimestamp() == $time ) ) {
 113                         return $img;
 114                 }
 115                 # Now try an old version of the file
 116                 if ( $time !== false ) {
 117                         $img = $this->newFile( $title, $time );
 118                         if ( $img && $img->exists() ) {
 119                                 if ( !$img->isDeleted(File::DELETED_FILE) ) {
 120                                         return $img;
 121                                 } else if ( !empty( $options['private'] )  && $img->userCan(File::DELETED_FILE) ) {
 122                                         return $img;
 123                                 }
 124                         }
 125                 }
 126
 127                 # Now try redirects
 128                 if ( !empty( $options['ignoreRedirect'] ) ) {
 129                         return false;
 130                 }
 131                 $redir = $this->checkRedirect( $title );
 132                 if( $redir && $redir->getNamespace() == NS_FILE) {
 133                         $img = $this->newFile( $redir );
 134                         if( !$img ) {
 135                                 return false;
 136                         }
 137                         if( $img->exists() ) {
 138                                 $img->redirectedFrom( $title->getDBkey() );
 139                                 return $img;
 140                         }
 141                 }
 142                 return false;
 143         }
 144
 145         /*
 146          * Find many files at once.
 147          * @param array $items, an array of titles, or an array of findFile() options with
 148          *    the "title" option giving the title. Example:
 149          *
 150          *     $findItem = array( 'title' => $title, 'private' => true );
 151          *     $findBatch = array( $findItem );
 152          *     $repo->findFiles( $findBatch );
 153          */
 154         function findFiles( $items ) {
 155                 $result = array();
 156                 foreach ( $items as $index => $item ) {
 157                         if ( is_array( $item ) ) {
 158                                 $title = $item['title'];
 159                                 $options = $item;
 160                                 unset( $options['title'] );
 161                         } else {
 162                                 $title = $item;
 163                                 $options = array();
 164                         }
 165                         $file = $this->findFile( $title, $options );
 166                         if ( $file )
 167                                 $result[$file->getTitle()->getDBkey()] = $file;
 168                 }
 169                 return $result;
 170         }
 171
 172         /**
 173          * Create a new File object from the local repository
 174          * @param mixed $sha1 SHA-1 key
 175          * @param mixed $time Time at which the image was uploaded.
 176          *                    If this is specified, the returned object will be an
 177          *                    instance of the repository's old file class instead of
 178          *                    a current file. Repositories not supporting version
 179          *                    control should return false if this parameter is set.
 180          */
 181         function newFileFromKey( $sha1, $time = false ) {
 182                 if ( $time ) {
 183                         if ( $this->oldFileFactoryKey ) {
 184                                 return call_user_func( $this->oldFileFactoryKey, $sha1, $this, $time );
 185                         } else {
 186                                 return false;
 187                         }
 188                 } else {
 189                         return call_user_func( $this->fileFactoryKey, $sha1, $this );
 190                 }
 191         }
 192
 193         /**
 194          * Find an instance of the file with this key, created at the specified time
 195          * Returns false if the file does not exist. Repositories not supporting
 196          * version control should return false if the time is specified.
 197          *
 198          * @param string $sha1 string
 199          * @param array $options Option array, same as findFile().
 200          */
 201         function findFileFromKey( $sha1, $options = array() ) {
 202                 if ( !is_array( $options ) ) {
 203                         # MW 1.15 compat
 204                         $time = $options;
 205                 } else {
 206                         $time = isset( $options['time'] ) ? $options['time'] : false;
 207                 }
 208
 209                 # First try the current version of the file to see if it precedes the timestamp
 210                 $img = $this->newFileFromKey( $sha1 );
 211                 if ( !$img ) {
 212                         return false;
 213                 }
 214                 if ( $img->exists() && ( !$time || $img->getTimestamp() == $time ) ) {
 215                         return $img;
 216                 }
 217                 # Now try an old version of the file
 218                 if ( $time !== false ) {
 219                         $img = $this->newFileFromKey( $sha1, $time );
 220                         if ( $img->exists() ) {
 221                                 if ( !$img->isDeleted(File::DELETED_FILE) ) {
 222                                         return $img;
 223                                 } else if ( !empty( $options['private'] ) && $img->userCan(File::DELETED_FILE) ) {
 224                                         return $img;
 225                                 }
 226                         }
 227                 }
 228                 return false;
 229         }
 230
 231         /**
 232          * Get the URL of thumb.php
 233          */
 234         function getThumbScriptUrl() {
 235                 return $this->thumbScriptUrl;
 236         }
 237
 238         /**
 239          * Get the URL corresponding to one of the four basic zones
 240          * @param String $zone One of: public, deleted, temp, thumb
 241          * @return String or false
 242          */
 243         function getZoneUrl( $zone ) {
 244                 return false;
 245         }
 246
 247         /**
 248          * Returns true if the repository can transform files via a 404 handler
 249          */
 250         function canTransformVia404() {
 251                 return $this->transformVia404;
 252         }
 253
 254         /**
 255          * Get the name of an image from its title object
 256          */
 257         function getNameFromTitle( $title ) {
 258                 global $wgCapitalLinks;
 259                 if ( $this->initialCapital != MWNamespace::isCapitalized( NS_FILE ) ) {
 260                         global $wgContLang;
 261                         $name = $title->getUserCaseDBKey();
 262                         if ( $this->initialCapital ) {
 263                                 $name = $wgContLang->ucfirst( $name );
 264                         }
 265                 } else {
 266                         $name = $title->getDBkey();
 267                 }
 268                 return $name;
 269         }
 270
 271         static function getHashPathForLevel( $name, $levels ) {
 272                 if ( $levels == 0 ) {
 273                         return '';
 274                 } else {
 275                         $hash = md5( $name );
 276                         $path = '';
 277                         for ( $i = 1; $i <= $levels; $i++ ) {
 278                                 $path .= substr( $hash, 0, $i ) . '/';
 279                         }
 280                         return $path;
 281                 }
 282         }
 283
 284         /**
 285          * Get a relative path including trailing slash, e.g. f/fa/
 286          * If the repo is not hashed, returns an empty string
 287          */
 288         function getHashPath( $name ) {
 289                 return self::getHashPathForLevel( $name, $this->hashLevels );
 290         }
 291
 292         /**
 293          * Get the name of this repository, as specified by $info['name]' to the constructor
 294          */
 295         function getName() {
 296                 return $this->name;
 297         }
 298
 299         /**
 300          * Get the URL of an image description page. May return false if it is
 301          * unknown or not applicable. In general this should only be called by the
 302          * File class, since it may return invalid results for certain kinds of
 303          * repositories. Use File::getDescriptionUrl() in user code.
 304          *
 305          * In particular, it uses the article paths as specified to the repository
 306          * constructor, whereas local repositories use the local Title functions.
 307          */
 308         function getDescriptionUrl( $name ) {
 309                 $encName = wfUrlencode( $name );
 310                 if ( !is_null( $this->descBaseUrl ) ) {
 311                         # "http://example.com/wiki/Image:"
 312                         return $this->descBaseUrl . $encName;
 313                 }
 314                 if ( !is_null( $this->articleUrl ) ) {
 315                         # "http://example.com/wiki/$1"
 316                         #
 317                         # We use "Image:" as the canonical namespace for
 318                         # compatibility across all MediaWiki versions.
 319                         return str_replace( '$1',
 320                                 "Image:$encName", $this->articleUrl );
 321                 }
 322                 if ( !is_null( $this->scriptDirUrl ) ) {
 323                         # "http://example.com/w"
 324                         #
 325                         # We use "Image:" as the canonical namespace for
 326                         # compatibility across all MediaWiki versions,
 327                         # and just sort of hope index.php is right. ;)
 328                         return $this->scriptDirUrl .
 329                                 "/index.php?title=Image:$encName";
 330                 }
 331                 return false;
 332         }
 333
 334         /**
 335          * Get the URL of the content-only fragment of the description page. For
 336          * MediaWiki this means action=render. This should only be called by the
 337          * repository's file class, since it may return invalid results. User code
 338          * should use File::getDescriptionText().
 339          * @param string $name Name of image to fetch
 340          * @param string $lang Language to fetch it in, if any.
 341          */
 342         function getDescriptionRenderUrl( $name, $lang = null ) {
 343                 $query = 'action=render';
 344                 if ( !is_null( $lang ) ) {
 345                         $query .= '&uselang=' . $lang;
 346                 }
 347                 if ( isset( $this->scriptDirUrl ) ) {
 348                         return $this->scriptDirUrl . '/index.php?title=' .
 349                                 wfUrlencode( 'Image:' . $name ) .
 350                                 "&$query";
 351                 } else {
 352                         $descUrl = $this->getDescriptionUrl( $name );
 353                         if ( $descUrl ) {
 354                                 return wfAppendQuery( $descUrl, $query );
 355                         } else {
 356                                 return false;
 357                         }
 358                 }
 359         }
 360
 361         /**
 362          * Store a file to a given destination.
 363          *
 364          * @param string $srcPath Source path or virtual URL
 365          * @param string $dstZone Destination zone
 366          * @param string $dstRel Destination relative path
 367          * @param integer $flags Bitwise combination of the following flags:
 368          *     self::DELETE_SOURCE     Delete the source file after upload
 369          *     self::OVERWRITE         Overwrite an existing destination file instead of failing
 370          *     self::OVERWRITE_SAME    Overwrite the file if the destination exists and has the
 371          *                             same contents as the source
 372          * @return FileRepoStatus
 373          */
 374         function store( $srcPath, $dstZone, $dstRel, $flags = 0 ) {
 375                 $status = $this->storeBatch( array( array( $srcPath, $dstZone, $dstRel ) ), $flags );
 376                 if ( $status->successCount == 0 ) {
 377                         $status->ok = false;
 378                 }
 379                 return $status;
 380         }
 381
 382         /**
 383          * Store a batch of files
 384          *
 385          * @param array $triplets (src,zone,dest) triplets as per store()
 386          * @param integer $flags Flags as per store
 387          */
 388         abstract function storeBatch( $triplets, $flags = 0 );
 389
 390         /**
 391          * Pick a random name in the temp zone and store a file to it.
 392          * Returns a FileRepoStatus object with the URL in the value.
 393          *
 394          * @param string $originalName The base name of the file as specified
 395          *     by the user. The file extension will be maintained.
 396          * @param string $srcPath The current location of the file.
 397          */
 398         abstract function storeTemp( $originalName, $srcPath );
 399
 400         abstract function append( $srcPath, $toAppendPath );
 401
 402         /**
 403          * Remove a temporary file or mark it for garbage collection
 404          * @param string $virtualUrl The virtual URL returned by storeTemp
 405          * @return boolean True on success, false on failure
 406          * STUB
 407          */
 408         function freeTemp( $virtualUrl ) {
 409                 return true;
 410         }
 411
 412         /**
 413          * Copy or move a file either from the local filesystem or from an mwrepo://
 414          * virtual URL, into this repository at the specified destination location.
 415          *
 416          * Returns a FileRepoStatus object. On success, the value contains "new" or
 417          * "archived", to indicate whether the file was new with that name.
 418          *
 419          * @param string $srcPath The source path or URL
 420          * @param string $dstRel The destination relative path
 421          * @param string $archiveRel The relative path where the existing file is to
 422          *        be archived, if there is one. Relative to the public zone root.
 423          * @param integer $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate
 424          *        that the source file should be deleted if possible
 425          */
 426         function publish( $srcPath, $dstRel, $archiveRel, $flags = 0 ) {
 427                 $status = $this->publishBatch( array( array( $srcPath, $dstRel, $archiveRel ) ), $flags );
 428                 if ( $status->successCount == 0 ) {
 429                         $status->ok = false;
 430                 }
 431                 if ( isset( $status->value[0] ) ) {
 432                         $status->value = $status->value[0];
 433                 } else {
 434                         $status->value = false;
 435                 }
 436                 return $status;
 437         }
 438
 439         /**
 440          * Publish a batch of files
 441          * @param array $triplets (source,dest,archive) triplets as per publish()
 442          * @param integer $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate
 443          *        that the source files should be deleted if possible
 444          */
 445         abstract function publishBatch( $triplets, $flags = 0 );
 446
 447         function fileExists( $file, $flags = 0 ) {
 448                 $result = $this->fileExistsBatch( array( $file ), $flags );
 449                 return $result[0];
 450         }
 451
 452         /**
 453          * Checks existence of an array of files.
 454          *
 455          * @param array $files URLs (or paths) of files to check
 456          * @param integer $flags Bitwise combination of the following flags:
 457          *     self::FILES_ONLY     Mark file as existing only if it is a file (not directory)
 458          * @return Either array of files and existence flags, or false
 459          */
 460         abstract function fileExistsBatch( $files, $flags = 0 );
 461
 462         /**
 463          * Move a group of files to the deletion archive.
 464          *
 465          * If no valid deletion archive is configured, this may either delete the
 466          * file or throw an exception, depending on the preference of the repository.
 467          *
 468          * The overwrite policy is determined by the repository -- currently FSRepo
 469          * assumes a naming scheme in the deleted zone based on content hash, as
 470          * opposed to the public zone which is assumed to be unique.
 471          *
 472          * @param array $sourceDestPairs Array of source/destination pairs. Each element
 473          *        is a two-element array containing the source file path relative to the
 474          *        public root in the first element, and the archive file path relative
 475          *        to the deleted zone root in the second element.
 476          * @return FileRepoStatus
 477          */
 478         abstract function deleteBatch( $sourceDestPairs );
 479
 480         /**
 481          * Move a file to the deletion archive.
 482          * If no valid deletion archive exists, this may either delete the file
 483          * or throw an exception, depending on the preference of the repository
 484          * @param mixed $srcRel Relative path for the file to be deleted
 485          * @param mixed $archiveRel Relative path for the archive location.
 486          *        Relative to a private archive directory.
 487          * @return WikiError object (wikitext-formatted), or true for success
 488          */
 489         function delete( $srcRel, $archiveRel ) {
 490                 return $this->deleteBatch( array( array( $srcRel, $archiveRel ) ) );
 491         }
 492
 493         /**
 494          * Get properties of a file with a given virtual URL
 495          * The virtual URL must refer to this repo
 496          * Properties should ultimately be obtained via File::getPropsFromPath()
 497          */
 498         abstract function getFileProps( $virtualUrl );
 499
 500         /**
 501          * Call a callback function for every file in the repository
 502          * May use either the database or the filesystem
 503          * STUB
 504          */
 505         function enumFiles( $callback ) {
 506                 throw new MWException( 'enumFiles is not supported by ' . get_class( $this ) );
 507         }
 508
 509         /**
 510          * Determine if a relative path is valid, i.e. not blank or involving directory traveral
 511          */
 512         function validateFilename( $filename ) {
 513                 if ( strval( $filename ) == '' ) {
 514                         return false;
 515                 }
 516                 if ( wfIsWindows() ) {
 517                         $filename = strtr( $filename, '\\', '/' );
 518                 }
 519                 /**
 520                  * Use the same traversal protection as Title::secureAndSplit()
 521                  */
 522                 if ( strpos( $filename, '.' ) !== false &&
 523                      ( $filename === '.' || $filename === '..' ||
 524                        strpos( $filename, './' ) === 0  ||
 525                        strpos( $filename, '../' ) === 0 ||
 526                        strpos( $filename, '/./' ) !== false ||
 527                        strpos( $filename, '/../' ) !== false ) )
 528                 {
 529                         return false;
 530                 } else {
 531                         return true;
 532                 }
 533         }
 534
 535         /**#@+
 536          * Path disclosure protection functions
 537          */
 538         function paranoidClean( $param ) { return '[hidden]'; }
 539         function passThrough( $param ) { return $param; }
 540
 541         /**
 542          * Get a callback function to use for cleaning error message parameters
 543          */
 544         function getErrorCleanupFunction() {
 545                 switch ( $this->pathDisclosureProtection ) {
 546                         case 'none':
 547                                 $callback = array( $this, 'passThrough' );
 548                                 break;
 549                         default: // 'paranoid'
 550                                 $callback = array( $this, 'paranoidClean' );
 551                 }
 552                 return $callback;
 553         }
 554         /**#@-*/
 555
 556         /**
 557          * Create a new fatal error
 558          */
 559         function newFatal( $message /*, parameters...*/ ) {
 560                 $params = func_get_args();
 561                 array_unshift( $params, $this );
 562                 return call_user_func_array( array( 'FileRepoStatus', 'newFatal' ), $params );
 563         }
 564
 565         /**
 566          * Create a new good result
 567          */
 568         function newGood( $value = null ) {
 569                 return FileRepoStatus::newGood( $this, $value );
 570         }
 571
 572         /**
 573          * Delete files in the deleted directory if they are not referenced in the filearchive table
 574          * STUB
 575          */
 576         function cleanupDeletedBatch( $storageKeys ) {}
 577
 578         /**
 579          * Checks if there is a redirect named as $title. If there is, return the
 580          * title object. If not, return false.
 581          * STUB
 582          *
 583          * @param Title $title Title of image
 584          */
 585         function checkRedirect( $title ) {
 586                 return false;
 587         }
 588
 589         /**
 590          * Invalidates image redirect cache related to that image
 591          * Doesn't do anything for repositories that don't support image redirects.
 592          *
 593          * STUB
 594          * @param Title $title Title of image
 595          */
 596         function invalidateImageRedirect( $title ) {}
 597
 598         /**
 599          * Get an array or iterator of file objects for files that have a given
 600          * SHA-1 content hash.
 601          *
 602          * STUB
 603          */
 604         function findBySha1( $hash ) {
 605                 return array();
 606         }
 607
 608         /**
 609          * Get the human-readable name of the repo.
 610          * @return string
 611          */
 612         public function getDisplayName() {
 613                 // We don't name our own repo, return nothing
 614                 if ( $this->name == 'local' ) {
 615                         return null;
 616                 }
 617                 $repoName = wfMsg( 'shared-repo-name-' . $this->name );
 618                 if ( !wfEmptyMsg( 'shared-repo-name-' . $this->name, $repoName ) ) {
 619                         return $repoName;
 620                 }
 621                 return wfMsg( 'shared-repo' );
 622         }
 623
 624         /**
 625          * Get a key on the primary cache for this repository.
 626          * Returns false if the repository's cache is not accessible at this site.
 627          * The parameters are the parts of the key, as for wfMemcKey().
 628          *
 629          * STUB
 630          */
 631         function getSharedCacheKey( /*...*/ ) {
 632                 return false;
 633         }
 634
 635         /**
 636          * Get a key for this repo in the local cache domain. These cache keys are
 637          * not shared with remote instances of the repo.
 638          * The parameters are the parts of the key, as for wfMemcKey().
 639          */
 640         function getLocalCacheKey( /*...*/ ) {
 641                 $args = func_get_args();
 642                 array_unshift( $args, 'filerepo', $this->getName() );
 643                 return call_user_func_array( 'wfMemcKey', $args );
 644         }
 645 }