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
 401         /**
 402          * Append the contents of the source path to the given file.
 403          * @param $srcPath string location of the source file
 404          * @param $toAppendPath string path to append to.
 405          * @param $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate
 406          *        that the source file should be deleted if possible
 407          * @return mixed Status or false
 408          */
 409         abstract function append( $srcPath, $toAppendPath, $flags = 0 );
 410
 411         /**
 412          * Remove a temporary file or mark it for garbage collection
 413          * @param string $virtualUrl The virtual URL returned by storeTemp
 414          * @return boolean True on success, false on failure
 415          * STUB
 416          */
 417         function freeTemp( $virtualUrl ) {
 418                 return true;
 419         }
 420
 421         /**
 422          * Copy or move a file either from the local filesystem or from an mwrepo://
 423          * virtual URL, into this repository at the specified destination location.
 424          *
 425          * Returns a FileRepoStatus object. On success, the value contains "new" or
 426          * "archived", to indicate whether the file was new with that name.
 427          *
 428          * @param string $srcPath The source path or URL
 429          * @param string $dstRel The destination relative path
 430          * @param string $archiveRel The relative path where the existing file is to
 431          *        be archived, if there is one. Relative to the public zone root.
 432          * @param integer $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate
 433          *        that the source file should be deleted if possible
 434          */
 435         function publish( $srcPath, $dstRel, $archiveRel, $flags = 0 ) {
 436                 $status = $this->publishBatch( array( array( $srcPath, $dstRel, $archiveRel ) ), $flags );
 437                 if ( $status->successCount == 0 ) {
 438                         $status->ok = false;
 439                 }
 440                 if ( isset( $status->value[0] ) ) {
 441                         $status->value = $status->value[0];
 442                 } else {
 443                         $status->value = false;
 444                 }
 445                 return $status;
 446         }
 447
 448         /**
 449          * Publish a batch of files
 450          * @param array $triplets (source,dest,archive) triplets as per publish()
 451          * @param integer $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate
 452          *        that the source files should be deleted if possible
 453          */
 454         abstract function publishBatch( $triplets, $flags = 0 );
 455
 456         function fileExists( $file, $flags = 0 ) {
 457                 $result = $this->fileExistsBatch( array( $file ), $flags );
 458                 return $result[0];
 459         }
 460
 461         /**
 462          * Checks existence of an array of files.
 463          *
 464          * @param array $files URLs (or paths) of files to check
 465          * @param integer $flags Bitwise combination of the following flags:
 466          *     self::FILES_ONLY     Mark file as existing only if it is a file (not directory)
 467          * @return Either array of files and existence flags, or false
 468          */
 469         abstract function fileExistsBatch( $files, $flags = 0 );
 470
 471         /**
 472          * Move a group of files to the deletion archive.
 473          *
 474          * If no valid deletion archive is configured, this may either delete the
 475          * file or throw an exception, depending on the preference of the repository.
 476          *
 477          * The overwrite policy is determined by the repository -- currently FSRepo
 478          * assumes a naming scheme in the deleted zone based on content hash, as
 479          * opposed to the public zone which is assumed to be unique.
 480          *
 481          * @param array $sourceDestPairs Array of source/destination pairs. Each element
 482          *        is a two-element array containing the source file path relative to the
 483          *        public root in the first element, and the archive file path relative
 484          *        to the deleted zone root in the second element.
 485          * @return FileRepoStatus
 486          */
 487         abstract function deleteBatch( $sourceDestPairs );
 488
 489         /**
 490          * Move a file to the deletion archive.
 491          * If no valid deletion archive exists, this may either delete the file
 492          * or throw an exception, depending on the preference of the repository
 493          * @param mixed $srcRel Relative path for the file to be deleted
 494          * @param mixed $archiveRel Relative path for the archive location.
 495          *        Relative to a private archive directory.
 496          * @return WikiError object (wikitext-formatted), or true for success
 497          */
 498         function delete( $srcRel, $archiveRel ) {
 499                 return $this->deleteBatch( array( array( $srcRel, $archiveRel ) ) );
 500         }
 501
 502         /**
 503          * Get properties of a file with a given virtual URL
 504          * The virtual URL must refer to this repo
 505          * Properties should ultimately be obtained via File::getPropsFromPath()
 506          */
 507         abstract function getFileProps( $virtualUrl );
 508
 509         /**
 510          * Call a callback function for every file in the repository
 511          * May use either the database or the filesystem
 512          * STUB
 513          */
 514         function enumFiles( $callback ) {
 515                 throw new MWException( 'enumFiles is not supported by ' . get_class( $this ) );
 516         }
 517
 518         /**
 519          * Determine if a relative path is valid, i.e. not blank or involving directory traveral
 520          */
 521         function validateFilename( $filename ) {
 522                 if ( strval( $filename ) == '' ) {
 523                         return false;
 524                 }
 525                 if ( wfIsWindows() ) {
 526                         $filename = strtr( $filename, '\\', '/' );
 527                 }
 528                 /**
 529                  * Use the same traversal protection as Title::secureAndSplit()
 530                  */
 531                 if ( strpos( $filename, '.' ) !== false &&
 532                      ( $filename === '.' || $filename === '..' ||
 533                        strpos( $filename, './' ) === 0  ||
 534                        strpos( $filename, '../' ) === 0 ||
 535                        strpos( $filename, '/./' ) !== false ||
 536                        strpos( $filename, '/../' ) !== false ) )
 537                 {
 538                         return false;
 539                 } else {
 540                         return true;
 541                 }
 542         }
 543
 544         /**#@+
 545          * Path disclosure protection functions
 546          */
 547         function paranoidClean( $param ) { return '[hidden]'; }
 548         function passThrough( $param ) { return $param; }
 549
 550         /**
 551          * Get a callback function to use for cleaning error message parameters
 552          */
 553         function getErrorCleanupFunction() {
 554                 switch ( $this->pathDisclosureProtection ) {
 555                         case 'none':
 556                                 $callback = array( $this, 'passThrough' );
 557                                 break;
 558                         default: // 'paranoid'
 559                                 $callback = array( $this, 'paranoidClean' );
 560                 }
 561                 return $callback;
 562         }
 563         /**#@-*/
 564
 565         /**
 566          * Create a new fatal error
 567          */
 568         function newFatal( $message /*, parameters...*/ ) {
 569                 $params = func_get_args();
 570                 array_unshift( $params, $this );
 571                 return call_user_func_array( array( 'FileRepoStatus', 'newFatal' ), $params );
 572         }
 573
 574         /**
 575          * Create a new good result
 576          */
 577         function newGood( $value = null ) {
 578                 return FileRepoStatus::newGood( $this, $value );
 579         }
 580
 581         /**
 582          * Delete files in the deleted directory if they are not referenced in the filearchive table
 583          * STUB
 584          */
 585         function cleanupDeletedBatch( $storageKeys ) {}
 586
 587         /**
 588          * Checks if there is a redirect named as $title. If there is, return the
 589          * title object. If not, return false.
 590          * STUB
 591          *
 592          * @param Title $title Title of image
 593          */
 594         function checkRedirect( $title ) {
 595                 return false;
 596         }
 597
 598         /**
 599          * Invalidates image redirect cache related to that image
 600          * Doesn't do anything for repositories that don't support image redirects.
 601          *
 602          * STUB
 603          * @param Title $title Title of image
 604          */
 605         function invalidateImageRedirect( $title ) {}
 606
 607         /**
 608          * Get an array or iterator of file objects for files that have a given
 609          * SHA-1 content hash.
 610          *
 611          * STUB
 612          */
 613         function findBySha1( $hash ) {
 614                 return array();
 615         }
 616
 617         /**
 618          * Get the human-readable name of the repo.
 619          * @return string
 620          */
 621         public function getDisplayName() {
 622                 // We don't name our own repo, return nothing
 623                 if ( $this->name == 'local' ) {
 624                         return null;
 625                 }
 626                 $repoName = wfMsg( 'shared-repo-name-' . $this->name );
 627                 if ( !wfEmptyMsg( 'shared-repo-name-' . $this->name, $repoName ) ) {
 628                         return $repoName;
 629                 }
 630                 return wfMsg( 'shared-repo' );
 631         }
 632
 633         /**
 634          * Get a key on the primary cache for this repository.
 635          * Returns false if the repository's cache is not accessible at this site.
 636          * The parameters are the parts of the key, as for wfMemcKey().
 637          *
 638          * STUB
 639          */
 640         function getSharedCacheKey( /*...*/ ) {
 641                 return false;
 642         }
 643
 644         /**
 645          * Get a key for this repo in the local cache domain. These cache keys are
 646          * not shared with remote instances of the repo.
 647          * The parameters are the parts of the key, as for wfMemcKey().
 648          */
 649         function getLocalCacheKey( /*...*/ ) {
 650                 $args = func_get_args();
 651                 array_unshift( $args, 'filerepo', $this->getName() );
 652                 return call_user_func_array( 'wfMemcKey', $args );
 653         }
 654 }