includes/filerepo/FileRepo.php

   1 <?php
   2
   3 /**
   4  * Base class for file repositories
   5  * Do not instantiate, use a derived class.
   6  */
   7 abstract class FileRepo {
   8         const DELETE_SOURCE = 1;
   9         const OVERWRITE = 2;
  10         const OVERWRITE_SAME = 4;
  11
  12         var $thumbScriptUrl, $transformVia404;
  13         var $descBaseUrl, $scriptDirUrl, $articleUrl, $fetchDescription, $initialCapital;
  14         var $pathDisclosureProtection = 'paranoid';
  15
  16         /**
  17          * Factory functions for creating new files
  18          * Override these in the base class
  19          */
  20         var $fileFactory = false, $oldFileFactory = false;
  21
  22         function __construct( $info ) {
  23                 // Required settings
  24                 $this->name = $info['name'];
  25
  26                 // Optional settings
  27                 $this->initialCapital = true; // by default
  28                 foreach ( array( 'descBaseUrl', 'scriptDirUrl', 'articleUrl', 'fetchDescription',
  29                         'thumbScriptUrl', 'initialCapital', 'pathDisclosureProtection' ) as $var )
  30                 {
  31                         if ( isset( $info[$var] ) ) {
  32                                 $this->$var = $info[$var];
  33                         }
  34                 }
  35                 $this->transformVia404 = !empty( $info['transformVia404'] );
  36         }
  37
  38         /**
  39          * Determine if a string is an mwrepo:// URL
  40          */
  41         static function isVirtualUrl( $url ) {
  42                 return substr( $url, 0, 9 ) == 'mwrepo://';
  43         }
  44
  45         /**
  46          * Create a new File object from the local repository
  47          * @param mixed $title Title object or string
  48          * @param mixed $time Time at which the image is supposed to have existed.
  49          *                    If this is specified, the returned object will be an
  50          *                    instance of the repository's old file class instead of
  51          *                    a current file. Repositories not supporting version
  52          *                    control should return false if this parameter is set.
  53          */
  54         function newFile( $title, $time = false ) {
  55                 if ( !($title instanceof Title) ) {
  56                         $title = Title::makeTitleSafe( NS_IMAGE, $title );
  57                         if ( !is_object( $title ) ) {
  58                                 return null;
  59                         }
  60                 }
  61                 if ( $time ) {
  62                         if ( $this->oldFileFactory ) {
  63                                 return call_user_func( $this->oldFileFactory, $title, $this, $time );
  64                         } else {
  65                                 return false;
  66                         }
  67                 } else {
  68                         return call_user_func( $this->fileFactory, $title, $this );
  69                 }
  70         }
  71
  72         /**
  73          * Find an instance of the named file that existed at the specified time
  74          * Returns false if the file did not exist. Repositories not supporting
  75          * version control should return false if the time is specified.
  76          *
  77          * @param mixed $time 14-character timestamp, or false for the current version
  78          */
  79         function findFile( $title, $time = false, $redirected = false ) {
  80                 if ( !($title instanceof Title) ) {
  81                         $title = Title::makeTitleSafe( NS_IMAGE, $title );
  82                         if ( !is_object( $title ) ) {
  83                                 return null;
  84                         }
  85                 }
  86
  87                 # First try the current version of the file to see if it precedes the timestamp
  88                 $img = $this->newFile( $title );
  89                 if ( !$img ) {
  90                         return false;
  91                 }
  92                 if ( $img->exists() && ( !$time || $img->getTimestamp() <= $time ) ) {
  93                         return $img;
  94                 }
  95                 # Now try an old version of the file
  96                 $img = $this->newFile( $title, $time );
  97                 if ( $img->exists() ) {
  98                         return $img;
  99                 }
 100
 101                 #Try redirects
 102                 if( !$redirected ) {    // Prevent redirect loops
 103                         $redir = $this->checkRedirects( $title->getDBkey() );
 104                         if( $redir )
 105                                 return $this->findFile( $redir, $time, $title );
 106                 }
 107         }
 108
 109         /**
 110          * Get the URL of thumb.php
 111          */
 112         function getThumbScriptUrl() {
 113                 return $this->thumbScriptUrl;
 114         }
 115
 116         /**
 117          * Returns true if the repository can transform files via a 404 handler
 118          */
 119         function canTransformVia404() {
 120                 return $this->transformVia404;
 121         }
 122
 123         /**
 124          * Get the name of an image from its title object
 125          */
 126         function getNameFromTitle( $title ) {
 127                 global $wgCapitalLinks;
 128                 if ( $this->initialCapital != $wgCapitalLinks ) {
 129                         global $wgContLang;
 130                         $name = $title->getUserCaseDBKey();
 131                         if ( $this->initialCapital ) {
 132                                 $name = $wgContLang->ucfirst( $name );
 133                         }
 134                 } else {
 135                         $name = $title->getDBkey();
 136                 }
 137                 return $name;
 138         }
 139
 140         static function getHashPathForLevel( $name, $levels ) {
 141                 if ( $levels == 0 ) {
 142                         return '';
 143                 } else {
 144                         $hash = md5( $name );
 145                         $path = '';
 146                         for ( $i = 1; $i <= $levels; $i++ ) {
 147                                 $path .= substr( $hash, 0, $i ) . '/';
 148                         }
 149                         return $path;
 150                 }
 151         }
 152
 153         /**
 154          * Get the name of this repository, as specified by $info['name]' to the constructor
 155          */
 156         function getName() {
 157                 return $this->name;
 158         }
 159
 160         /**
 161          * Get the file description page base URL, or false if there isn't one.
 162          * @private
 163          */
 164         function getDescBaseUrl() {
 165                 if ( is_null( $this->descBaseUrl ) ) {
 166                         if ( !is_null( $this->articleUrl ) ) {
 167                                 $this->descBaseUrl = str_replace( '$1',
 168                                         wfUrlencode( Namespace::getCanonicalName( NS_IMAGE ) ) . ':', $this->articleUrl );
 169                         } elseif ( !is_null( $this->scriptDirUrl ) ) {
 170                                 $this->descBaseUrl = $this->scriptDirUrl . '/index.php?title=' .
 171                                         wfUrlencode( Namespace::getCanonicalName( NS_IMAGE ) ) . ':';
 172                         } else {
 173                                 $this->descBaseUrl = false;
 174                         }
 175                 }
 176                 return $this->descBaseUrl;
 177         }
 178
 179         /**
 180          * Get the URL of an image description page. May return false if it is
 181          * unknown or not applicable. In general this should only be called by the
 182          * File class, since it may return invalid results for certain kinds of
 183          * repositories. Use File::getDescriptionUrl() in user code.
 184          *
 185          * In particular, it uses the article paths as specified to the repository
 186          * constructor, whereas local repositories use the local Title functions.
 187          */
 188         function getDescriptionUrl( $name ) {
 189                 $base = $this->getDescBaseUrl();
 190                 if ( $base ) {
 191                         return $base . wfUrlencode( $name );
 192                 } else {
 193                         return false;
 194                 }
 195         }
 196
 197         /**
 198          * Get the URL of the content-only fragment of the description page. For
 199          * MediaWiki this means action=render. This should only be called by the
 200          * repository's file class, since it may return invalid results. User code
 201          * should use File::getDescriptionText().
 202          */
 203         function getDescriptionRenderUrl( $name ) {
 204                 if ( isset( $this->scriptDirUrl ) ) {
 205                         return $this->scriptDirUrl . '/index.php?title=' .
 206                                 wfUrlencode( Namespace::getCanonicalName( NS_IMAGE ) . ':' . $name ) .
 207                                 '&action=render';
 208                 } else {
 209                         $descBase = $this->getDescBaseUrl();
 210                         if ( $descBase ) {
 211                                 return wfAppendQuery( $descBase . wfUrlencode( $name ), 'action=render' );
 212                         } else {
 213                                 return false;
 214                         }
 215                 }
 216         }
 217
 218         /**
 219          * Store a file to a given destination.
 220          *
 221          * @param string $srcPath Source path or virtual URL
 222          * @param string $dstZone Destination zone
 223          * @param string $dstRel Destination relative path
 224          * @param integer $flags Bitwise combination of the following flags:
 225          *     self::DELETE_SOURCE     Delete the source file after upload
 226          *     self::OVERWRITE         Overwrite an existing destination file instead of failing
 227          *     self::OVERWRITE_SAME    Overwrite the file if the destination exists and has the
 228          *                             same contents as the source
 229          * @return FileRepoStatus
 230          */
 231         function store( $srcPath, $dstZone, $dstRel, $flags = 0 ) {
 232                 $status = $this->storeBatch( array( array( $srcPath, $dstZone, $dstRel ) ), $flags );
 233                 if ( $status->successCount == 0 ) {
 234                         $status->ok = false;
 235                 }
 236                 return $status;
 237         }
 238
 239         /**
 240          * Store a batch of files
 241          *
 242          * @param array $triplets (src,zone,dest) triplets as per store()
 243          * @param integer $flags Flags as per store
 244          */
 245         abstract function storeBatch( $triplets, $flags = 0 );
 246
 247         /**
 248          * Pick a random name in the temp zone and store a file to it.
 249          * Returns a FileRepoStatus object with the URL in the value.
 250          *
 251          * @param string $originalName The base name of the file as specified
 252          *     by the user. The file extension will be maintained.
 253          * @param string $srcPath The current location of the file.
 254          */
 255         abstract function storeTemp( $originalName, $srcPath );
 256
 257         /**
 258          * Remove a temporary file or mark it for garbage collection
 259          * @param string $virtualUrl The virtual URL returned by storeTemp
 260          * @return boolean True on success, false on failure
 261          * STUB
 262          */
 263         function freeTemp( $virtualUrl ) {
 264                 return true;
 265         }
 266
 267         /**
 268          * Copy or move a file either from the local filesystem or from an mwrepo://
 269          * virtual URL, into this repository at the specified destination location.
 270          *
 271          * Returns a FileRepoStatus object. On success, the value contains "new" or
 272          * "archived", to indicate whether the file was new with that name.
 273          *
 274          * @param string $srcPath The source path or URL
 275          * @param string $dstRel The destination relative path
 276          * @param string $archiveRel The relative path where the existing file is to
 277          *        be archived, if there is one. Relative to the public zone root.
 278          * @param integer $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate
 279          *        that the source file should be deleted if possible
 280          */
 281         function publish( $srcPath, $dstRel, $archiveRel, $flags = 0 ) {
 282                 $status = $this->publishBatch( array( array( $srcPath, $dstRel, $archiveRel ) ), $flags );
 283                 if ( $status->successCount == 0 ) {
 284                         $status->ok = false;
 285                 }
 286                 if ( isset( $status->value[0] ) ) {
 287                         $status->value = $status->value[0];
 288                 } else {
 289                         $status->value = false;
 290                 }
 291                 return $status;
 292         }
 293
 294         /**
 295          * Publish a batch of files
 296          * @param array $triplets (source,dest,archive) triplets as per publish()
 297          * @param integer $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate
 298          *        that the source files should be deleted if possible
 299          */
 300         abstract function publishBatch( $triplets, $flags = 0 );
 301
 302         /**
 303          * Move a group of files to the deletion archive.
 304          *
 305          * If no valid deletion archive is configured, this may either delete the
 306          * file or throw an exception, depending on the preference of the repository.
 307          *
 308          * The overwrite policy is determined by the repository -- currently FSRepo
 309          * assumes a naming scheme in the deleted zone based on content hash, as
 310          * opposed to the public zone which is assumed to be unique.
 311          *
 312          * @param array $sourceDestPairs Array of source/destination pairs. Each element
 313          *        is a two-element array containing the source file path relative to the
 314          *        public root in the first element, and the archive file path relative
 315          *        to the deleted zone root in the second element.
 316          * @return FileRepoStatus
 317          */
 318         abstract function deleteBatch( $sourceDestPairs );
 319
 320         /**
 321          * Move a file to the deletion archive.
 322          * If no valid deletion archive exists, this may either delete the file
 323          * or throw an exception, depending on the preference of the repository
 324          * @param mixed $srcRel Relative path for the file to be deleted
 325          * @param mixed $archiveRel Relative path for the archive location.
 326          *        Relative to a private archive directory.
 327          * @return WikiError object (wikitext-formatted), or true for success
 328          */
 329         function delete( $srcRel, $archiveRel ) {
 330                 return $this->deleteBatch( array( array( $srcRel, $archiveRel ) ) );
 331         }
 332
 333         /**
 334          * Get properties of a file with a given virtual URL
 335          * The virtual URL must refer to this repo
 336          * Properties should ultimately be obtained via File::getPropsFromPath()
 337          */
 338         abstract function getFileProps( $virtualUrl );
 339
 340         /**
 341          * Call a callback function for every file in the repository
 342          * May use either the database or the filesystem
 343          * STUB
 344          */
 345         function enumFiles( $callback ) {
 346                 throw new MWException( 'enumFiles is not supported by ' . get_class( $this ) );
 347         }
 348
 349         /**
 350          * Determine if a relative path is valid, i.e. not blank or involving directory traveral
 351          */
 352         function validateFilename( $filename ) {
 353                 if ( strval( $filename ) == '' ) {
 354                         return false;
 355                 }
 356                 if ( wfIsWindows() ) {
 357                         $filename = strtr( $filename, '\\', '/' );
 358                 }
 359                 /**
 360                  * Use the same traversal protection as Title::secureAndSplit()
 361                  */
 362                 if ( strpos( $filename, '.' ) !== false &&
 363                      ( $filename === '.' || $filename === '..' ||
 364                        strpos( $filename, './' ) === 0  ||
 365                        strpos( $filename, '../' ) === 0 ||
 366                        strpos( $filename, '/./' ) !== false ||
 367                        strpos( $filename, '/../' ) !== false ) )
 368                 {
 369                         return false;
 370                 } else {
 371                         return true;
 372                 }
 373         }
 374
 375         /**#@+
 376          * Path disclosure protection functions
 377          */
 378         function paranoidClean( $param ) { return '[hidden]'; }
 379         function passThrough( $param ) { return $param; }
 380
 381         /**
 382          * Get a callback function to use for cleaning error message parameters
 383          */
 384         function getErrorCleanupFunction() {
 385                 switch ( $this->pathDisclosureProtection ) {
 386                         case 'none':
 387                                 $callback = array( $this, 'passThrough' );
 388                                 break;
 389                         default: // 'paranoid'
 390                                 $callback = array( $this, 'paranoidClean' );
 391                 }
 392                 return $callback;
 393         }
 394         /**#@-*/
 395
 396         /**
 397          * Create a new fatal error
 398          */
 399         function newFatal( $message /*, parameters...*/ ) {
 400                 $params = func_get_args();
 401                 array_unshift( $params, $this );
 402                 return call_user_func_array( array( 'FileRepoStatus', 'newFatal' ), $params );
 403         }
 404
 405         /**
 406          * Create a new good result
 407          */
 408         function newGood( $value = null ) {
 409                 return FileRepoStatus::newGood( $this, $value );
 410         }
 411
 412         /**
 413          * Delete files in the deleted directory if they are not referenced in the filearchive table
 414          * STUB
 415          */
 416         function cleanupDeletedBatch( $storageKeys ) {}
 417
 418         /**
 419          * Check for redirects.
 420          */
 421         function checkRedirects( $filename ) {
 422                 $dbr = $this->getSlaveDB();
 423                 $res = $dbr->selectRow(
 424                         'imageredirects',
 425                         array( 'ir_from', 'ir_to' ),
 426                         array( 'ir_from' => $filename ),
 427                         __METHOD__
 428                 );
 429                 if( !$res ) return false;
 430                 return $res->ir_to;
 431         }
 432 }
 433