MediaWiki  master
FileRepo.php
Go to the documentation of this file.
1 <?php
37 class FileRepo {
38  const DELETE_SOURCE = 1;
39  const OVERWRITE = 2;
40  const OVERWRITE_SAME = 4;
41  const SKIP_LOCKING = 8;
42 
43  const NAME_AND_TIME_ONLY = 1;
44 
48 
51 
53  protected $hasSha1Storage = false;
54 
56  protected $supportsSha1URLs = false;
57 
59  protected $backend;
60 
62  protected $zones = [];
63 
65  protected $thumbScriptUrl;
66 
69  protected $transformVia404;
70 
74  protected $descBaseUrl;
75 
79  protected $scriptDirUrl;
80 
83  protected $scriptExtension;
84 
86  protected $articleUrl;
87 
93  protected $initialCapital;
94 
100  protected $pathDisclosureProtection = 'simple';
101 
103  protected $url;
104 
106  protected $thumbUrl;
107 
109  protected $hashLevels;
110 
113 
118  protected $abbrvThreshold;
119 
121  protected $favicon;
122 
124  protected $isPrivate;
125 
127  protected $fileFactory = [ 'UnregisteredLocalFile', 'newFromTitle' ];
129  protected $oldFileFactory = false;
131  protected $fileFactoryKey = false;
133  protected $oldFileFactoryKey = false;
134 
139  public function __construct( array $info = null ) {
140  // Verify required settings presence
141  if (
142  $info === null
143  || !array_key_exists( 'name', $info )
144  || !array_key_exists( 'backend', $info )
145  ) {
146  throw new MWException( __CLASS__ .
147  " requires an array of options having both 'name' and 'backend' keys.\n" );
148  }
149 
150  // Required settings
151  $this->name = $info['name'];
152  if ( $info['backend'] instanceof FileBackend ) {
153  $this->backend = $info['backend']; // useful for testing
154  } else {
155  $this->backend = FileBackendGroup::singleton()->get( $info['backend'] );
156  }
157 
158  // Optional settings that can have no value
159  $optionalSettings = [
160  'descBaseUrl', 'scriptDirUrl', 'articleUrl', 'fetchDescription',
161  'thumbScriptUrl', 'pathDisclosureProtection', 'descriptionCacheExpiry',
162  'scriptExtension', 'favicon'
163  ];
164  foreach ( $optionalSettings as $var ) {
165  if ( isset( $info[$var] ) ) {
166  $this->$var = $info[$var];
167  }
168  }
169 
170  // Optional settings that have a default
171  $this->initialCapital = isset( $info['initialCapital'] )
172  ? $info['initialCapital']
174  $this->url = isset( $info['url'] )
175  ? $info['url']
176  : false; // a subclass may set the URL (e.g. ForeignAPIRepo)
177  if ( isset( $info['thumbUrl'] ) ) {
178  $this->thumbUrl = $info['thumbUrl'];
179  } else {
180  $this->thumbUrl = $this->url ? "{$this->url}/thumb" : false;
181  }
182  $this->hashLevels = isset( $info['hashLevels'] )
183  ? $info['hashLevels']
184  : 2;
185  $this->deletedHashLevels = isset( $info['deletedHashLevels'] )
186  ? $info['deletedHashLevels']
188  $this->transformVia404 = !empty( $info['transformVia404'] );
189  $this->abbrvThreshold = isset( $info['abbrvThreshold'] )
190  ? $info['abbrvThreshold']
191  : 255;
192  $this->isPrivate = !empty( $info['isPrivate'] );
193  // Give defaults for the basic zones...
194  $this->zones = isset( $info['zones'] ) ? $info['zones'] : [];
195  foreach ( [ 'public', 'thumb', 'transcoded', 'temp', 'deleted' ] as $zone ) {
196  if ( !isset( $this->zones[$zone]['container'] ) ) {
197  $this->zones[$zone]['container'] = "{$this->name}-{$zone}";
198  }
199  if ( !isset( $this->zones[$zone]['directory'] ) ) {
200  $this->zones[$zone]['directory'] = '';
201  }
202  if ( !isset( $this->zones[$zone]['urlsByExt'] ) ) {
203  $this->zones[$zone]['urlsByExt'] = [];
204  }
205  }
206 
207  $this->supportsSha1URLs = !empty( $info['supportsSha1URLs'] );
208  }
209 
215  public function getBackend() {
216  return $this->backend;
217  }
218 
225  public function getReadOnlyReason() {
226  return $this->backend->getReadOnlyReason();
227  }
228 
236  protected function initZones( $doZones = [] ) {
237  $status = $this->newGood();
238  foreach ( (array)$doZones as $zone ) {
239  $root = $this->getZonePath( $zone );
240  if ( $root === null ) {
241  throw new MWException( "No '$zone' zone defined in the {$this->name} repo." );
242  }
243  }
244 
245  return $status;
246  }
247 
254  public static function isVirtualUrl( $url ) {
255  return substr( $url, 0, 9 ) == 'mwrepo://';
256  }
257 
266  public function getVirtualUrl( $suffix = false ) {
267  $path = 'mwrepo://' . $this->name;
268  if ( $suffix !== false ) {
269  $path .= '/' . rawurlencode( $suffix );
270  }
271 
272  return $path;
273  }
274 
282  public function getZoneUrl( $zone, $ext = null ) {
283  if ( in_array( $zone, [ 'public', 'thumb', 'transcoded' ] ) ) {
284  // standard public zones
285  if ( $ext !== null && isset( $this->zones[$zone]['urlsByExt'][$ext] ) ) {
286  // custom URL for extension/zone
287  return $this->zones[$zone]['urlsByExt'][$ext];
288  } elseif ( isset( $this->zones[$zone]['url'] ) ) {
289  // custom URL for zone
290  return $this->zones[$zone]['url'];
291  }
292  }
293  switch ( $zone ) {
294  case 'public':
295  return $this->url;
296  case 'temp':
297  case 'deleted':
298  return false; // no public URL
299  case 'thumb':
300  return $this->thumbUrl;
301  case 'transcoded':
302  return "{$this->url}/transcoded";
303  default:
304  return false;
305  }
306  }
307 
311  public function backendSupportsUnicodePaths() {
312  return (bool)( $this->getBackend()->getFeatures() & FileBackend::ATTR_UNICODE_PATHS );
313  }
314 
323  public function resolveVirtualUrl( $url ) {
324  if ( substr( $url, 0, 9 ) != 'mwrepo://' ) {
325  throw new MWException( __METHOD__ . ': unknown protocol' );
326  }
327  $bits = explode( '/', substr( $url, 9 ), 3 );
328  if ( count( $bits ) != 3 ) {
329  throw new MWException( __METHOD__ . ": invalid mwrepo URL: $url" );
330  }
331  list( $repo, $zone, $rel ) = $bits;
332  if ( $repo !== $this->name ) {
333  throw new MWException( __METHOD__ . ": fetching from a foreign repo is not supported" );
334  }
335  $base = $this->getZonePath( $zone );
336  if ( !$base ) {
337  throw new MWException( __METHOD__ . ": invalid zone: $zone" );
338  }
339 
340  return $base . '/' . rawurldecode( $rel );
341  }
342 
349  protected function getZoneLocation( $zone ) {
350  if ( !isset( $this->zones[$zone] ) ) {
351  return [ null, null ]; // bogus
352  }
353 
354  return [ $this->zones[$zone]['container'], $this->zones[$zone]['directory'] ];
355  }
356 
363  public function getZonePath( $zone ) {
364  list( $container, $base ) = $this->getZoneLocation( $zone );
365  if ( $container === null || $base === null ) {
366  return null;
367  }
368  $backendName = $this->backend->getName();
369  if ( $base != '' ) { // may not be set
370  $base = "/{$base}";
371  }
372 
373  return "mwstore://$backendName/{$container}{$base}";
374  }
375 
387  public function newFile( $title, $time = false ) {
389  if ( !$title ) {
390  return null;
391  }
392  if ( $time ) {
393  if ( $this->oldFileFactory ) {
394  return call_user_func( $this->oldFileFactory, $title, $this, $time );
395  } else {
396  return null;
397  }
398  } else {
399  return call_user_func( $this->fileFactory, $title, $this );
400  }
401  }
402 
420  public function findFile( $title, $options = [] ) {
422  if ( !$title ) {
423  return false;
424  }
425  if ( isset( $options['bypassCache'] ) ) {
426  $options['latest'] = $options['bypassCache']; // b/c
427  }
428  $time = isset( $options['time'] ) ? $options['time'] : false;
429  $flags = !empty( $options['latest'] ) ? File::READ_LATEST : 0;
430  # First try the current version of the file to see if it precedes the timestamp
431  $img = $this->newFile( $title );
432  if ( !$img ) {
433  return false;
434  }
435  $img->load( $flags );
436  if ( $img->exists() && ( !$time || $img->getTimestamp() == $time ) ) {
437  return $img;
438  }
439  # Now try an old version of the file
440  if ( $time !== false ) {
441  $img = $this->newFile( $title, $time );
442  if ( $img ) {
443  $img->load( $flags );
444  if ( $img->exists() ) {
445  if ( !$img->isDeleted( File::DELETED_FILE ) ) {
446  return $img; // always OK
447  } elseif ( !empty( $options['private'] ) &&
448  $img->userCan( File::DELETED_FILE,
449  $options['private'] instanceof User ? $options['private'] : null
450  )
451  ) {
452  return $img;
453  }
454  }
455  }
456  }
457 
458  # Now try redirects
459  if ( !empty( $options['ignoreRedirect'] ) ) {
460  return false;
461  }
462  $redir = $this->checkRedirect( $title );
463  if ( $redir && $title->getNamespace() == NS_FILE ) {
464  $img = $this->newFile( $redir );
465  if ( !$img ) {
466  return false;
467  }
468  $img->load( $flags );
469  if ( $img->exists() ) {
470  $img->redirectedFrom( $title->getDBkey() );
471 
472  return $img;
473  }
474  }
475 
476  return false;
477  }
478 
496  public function findFiles( array $items, $flags = 0 ) {
497  $result = [];
498  foreach ( $items as $item ) {
499  if ( is_array( $item ) ) {
500  $title = $item['title'];
501  $options = $item;
502  unset( $options['title'] );
503  } else {
504  $title = $item;
505  $options = [];
506  }
507  $file = $this->findFile( $title, $options );
508  if ( $file ) {
509  $searchName = File::normalizeTitle( $title )->getDBkey(); // must be valid
510  if ( $flags & self::NAME_AND_TIME_ONLY ) {
511  $result[$searchName] = [
512  'title' => $file->getTitle()->getDBkey(),
513  'timestamp' => $file->getTimestamp()
514  ];
515  } else {
516  $result[$searchName] = $file;
517  }
518  }
519  }
520 
521  return $result;
522  }
523 
533  public function findFileFromKey( $sha1, $options = [] ) {
534  $time = isset( $options['time'] ) ? $options['time'] : false;
535  # First try to find a matching current version of a file...
536  if ( !$this->fileFactoryKey ) {
537  return false; // find-by-sha1 not supported
538  }
539  $img = call_user_func( $this->fileFactoryKey, $sha1, $this, $time );
540  if ( $img && $img->exists() ) {
541  return $img;
542  }
543  # Now try to find a matching old version of a file...
544  if ( $time !== false && $this->oldFileFactoryKey ) { // find-by-sha1 supported?
545  $img = call_user_func( $this->oldFileFactoryKey, $sha1, $this, $time );
546  if ( $img && $img->exists() ) {
547  if ( !$img->isDeleted( File::DELETED_FILE ) ) {
548  return $img; // always OK
549  } elseif ( !empty( $options['private'] ) &&
550  $img->userCan( File::DELETED_FILE,
551  $options['private'] instanceof User ? $options['private'] : null
552  )
553  ) {
554  return $img;
555  }
556  }
557  }
558 
559  return false;
560  }
561 
570  public function findBySha1( $hash ) {
571  return [];
572  }
573 
581  public function findBySha1s( array $hashes ) {
582  $result = [];
583  foreach ( $hashes as $hash ) {
584  $files = $this->findBySha1( $hash );
585  if ( count( $files ) ) {
586  $result[$hash] = $files;
587  }
588  }
589 
590  return $result;
591  }
592 
601  public function findFilesByPrefix( $prefix, $limit ) {
602  return [];
603  }
604 
610  public function getThumbScriptUrl() {
611  return $this->thumbScriptUrl;
612  }
613 
619  public function canTransformVia404() {
620  return $this->transformVia404;
621  }
622 
629  public function getNameFromTitle( Title $title ) {
631  if ( $this->initialCapital != MWNamespace::isCapitalized( NS_FILE ) ) {
632  $name = $title->getUserCaseDBKey();
633  if ( $this->initialCapital ) {
634  $name = $wgContLang->ucfirst( $name );
635  }
636  } else {
637  $name = $title->getDBkey();
638  }
639 
640  return $name;
641  }
642 
648  public function getRootDirectory() {
649  return $this->getZonePath( 'public' );
650  }
651 
659  public function getHashPath( $name ) {
660  return self::getHashPathForLevel( $name, $this->hashLevels );
661  }
662 
670  public function getTempHashPath( $suffix ) {
671  $parts = explode( '!', $suffix, 2 ); // format is <timestamp>!<name> or just <name>
672  $name = isset( $parts[1] ) ? $parts[1] : $suffix; // hash path is not based on timestamp
673  return self::getHashPathForLevel( $name, $this->hashLevels );
674  }
675 
681  protected static function getHashPathForLevel( $name, $levels ) {
682  if ( $levels == 0 ) {
683  return '';
684  } else {
685  $hash = md5( $name );
686  $path = '';
687  for ( $i = 1; $i <= $levels; $i++ ) {
688  $path .= substr( $hash, 0, $i ) . '/';
689  }
690 
691  return $path;
692  }
693  }
694 
700  public function getHashLevels() {
701  return $this->hashLevels;
702  }
703 
709  public function getName() {
710  return $this->name;
711  }
712 
720  public function makeUrl( $query = '', $entry = 'index' ) {
721  if ( isset( $this->scriptDirUrl ) ) {
722  $ext = isset( $this->scriptExtension ) ? $this->scriptExtension : '.php';
723 
724  return wfAppendQuery( "{$this->scriptDirUrl}/{$entry}{$ext}", $query );
725  }
726 
727  return false;
728  }
729 
742  public function getDescriptionUrl( $name ) {
743  $encName = wfUrlencode( $name );
744  if ( !is_null( $this->descBaseUrl ) ) {
745  # "http://example.com/wiki/File:"
746  return $this->descBaseUrl . $encName;
747  }
748  if ( !is_null( $this->articleUrl ) ) {
749  # "http://example.com/wiki/$1"
750  # We use "Image:" as the canonical namespace for
751  # compatibility across all MediaWiki versions.
752  return str_replace( '$1',
753  "Image:$encName", $this->articleUrl );
754  }
755  if ( !is_null( $this->scriptDirUrl ) ) {
756  # "http://example.com/w"
757  # We use "Image:" as the canonical namespace for
758  # compatibility across all MediaWiki versions,
759  # and just sort of hope index.php is right. ;)
760  return $this->makeUrl( "title=Image:$encName" );
761  }
762 
763  return false;
764  }
765 
776  public function getDescriptionRenderUrl( $name, $lang = null ) {
777  $query = 'action=render';
778  if ( !is_null( $lang ) ) {
779  $query .= '&uselang=' . urlencode( $lang );
780  }
781  if ( isset( $this->scriptDirUrl ) ) {
782  return $this->makeUrl(
783  'title=' .
784  wfUrlencode( 'Image:' . $name ) .
785  "&$query" );
786  } else {
787  $descUrl = $this->getDescriptionUrl( $name );
788  if ( $descUrl ) {
789  return wfAppendQuery( $descUrl, $query );
790  } else {
791  return false;
792  }
793  }
794  }
795 
801  public function getDescriptionStylesheetUrl() {
802  if ( isset( $this->scriptDirUrl ) ) {
803  return $this->makeUrl( 'title=MediaWiki:Filepage.css&' .
805  }
806 
807  return false;
808  }
809 
823  public function store( $srcPath, $dstZone, $dstRel, $flags = 0 ) {
824  $this->assertWritableRepo(); // fail out if read-only
825 
826  $status = $this->storeBatch( [ [ $srcPath, $dstZone, $dstRel ] ], $flags );
827  if ( $status->successCount == 0 ) {
828  $status->setOK( false );
829  }
830 
831  return $status;
832  }
833 
846  public function storeBatch( array $triplets, $flags = 0 ) {
847  $this->assertWritableRepo(); // fail out if read-only
848 
849  if ( $flags & self::DELETE_SOURCE ) {
850  throw new InvalidArgumentException( "DELETE_SOURCE not supported in " . __METHOD__ );
851  }
852 
853  $status = $this->newGood();
854  $backend = $this->backend; // convenience
855 
856  $operations = [];
857  // Validate each triplet and get the store operation...
858  foreach ( $triplets as $triplet ) {
859  list( $srcPath, $dstZone, $dstRel ) = $triplet;
860  wfDebug( __METHOD__
861  . "( \$src='$srcPath', \$dstZone='$dstZone', \$dstRel='$dstRel' )\n"
862  );
863 
864  // Resolve destination path
865  $root = $this->getZonePath( $dstZone );
866  if ( !$root ) {
867  throw new MWException( "Invalid zone: $dstZone" );
868  }
869  if ( !$this->validateFilename( $dstRel ) ) {
870  throw new MWException( 'Validation error in $dstRel' );
871  }
872  $dstPath = "$root/$dstRel";
873  $dstDir = dirname( $dstPath );
874  // Create destination directories for this triplet
875  if ( !$this->initDirectory( $dstDir )->isOK() ) {
876  return $this->newFatal( 'directorycreateerror', $dstDir );
877  }
878 
879  // Resolve source to a storage path if virtual
880  $srcPath = $this->resolveToStoragePath( $srcPath );
881 
882  // Get the appropriate file operation
883  if ( FileBackend::isStoragePath( $srcPath ) ) {
884  $opName = 'copy';
885  } else {
886  $opName = 'store';
887  }
888  $operations[] = [
889  'op' => $opName,
890  'src' => $srcPath,
891  'dst' => $dstPath,
892  'overwrite' => $flags & self::OVERWRITE,
893  'overwriteSame' => $flags & self::OVERWRITE_SAME,
894  ];
895  }
896 
897  // Execute the store operation for each triplet
898  $opts = [ 'force' => true ];
899  if ( $flags & self::SKIP_LOCKING ) {
900  $opts['nonLocking'] = true;
901  }
902  $status->merge( $backend->doOperations( $operations, $opts ) );
903 
904  return $status;
905  }
906 
917  public function cleanupBatch( array $files, $flags = 0 ) {
918  $this->assertWritableRepo(); // fail out if read-only
919 
920  $status = $this->newGood();
921 
922  $operations = [];
923  foreach ( $files as $path ) {
924  if ( is_array( $path ) ) {
925  // This is a pair, extract it
926  list( $zone, $rel ) = $path;
927  $path = $this->getZonePath( $zone ) . "/$rel";
928  } else {
929  // Resolve source to a storage path if virtual
930  $path = $this->resolveToStoragePath( $path );
931  }
932  $operations[] = [ 'op' => 'delete', 'src' => $path ];
933  }
934  // Actually delete files from storage...
935  $opts = [ 'force' => true ];
936  if ( $flags & self::SKIP_LOCKING ) {
937  $opts['nonLocking'] = true;
938  }
939  $status->merge( $this->backend->doOperations( $operations, $opts ) );
940 
941  return $status;
942  }
943 
957  final public function quickImport( $src, $dst, $options = null ) {
958  return $this->quickImportBatch( [ [ $src, $dst, $options ] ] );
959  }
960 
969  final public function quickPurge( $path ) {
970  return $this->quickPurgeBatch( [ $path ] );
971  }
972 
980  public function quickCleanDir( $dir ) {
981  $status = $this->newGood();
982  $status->merge( $this->backend->clean(
983  [ 'dir' => $this->resolveToStoragePath( $dir ) ] ) );
984 
985  return $status;
986  }
987 
1000  public function quickImportBatch( array $triples ) {
1001  $status = $this->newGood();
1002  $operations = [];
1003  foreach ( $triples as $triple ) {
1004  list( $src, $dst ) = $triple;
1005  if ( $src instanceof FSFile ) {
1006  $op = 'store';
1007  } else {
1008  $src = $this->resolveToStoragePath( $src );
1009  $op = FileBackend::isStoragePath( $src ) ? 'copy' : 'store';
1010  }
1011  $dst = $this->resolveToStoragePath( $dst );
1012 
1013  if ( !isset( $triple[2] ) ) {
1014  $headers = [];
1015  } elseif ( is_string( $triple[2] ) ) {
1016  // back-compat
1017  $headers = [ 'Content-Disposition' => $triple[2] ];
1018  } elseif ( is_array( $triple[2] ) && isset( $triple[2]['headers'] ) ) {
1019  $headers = $triple[2]['headers'];
1020  } else {
1021  $headers = [];
1022  }
1023 
1024  $operations[] = [
1025  'op' => $op,
1026  'src' => $src,
1027  'dst' => $dst,
1028  'headers' => $headers
1029  ];
1030  $status->merge( $this->initDirectory( dirname( $dst ) ) );
1031  }
1032  $status->merge( $this->backend->doQuickOperations( $operations ) );
1033 
1034  return $status;
1035  }
1036 
1045  public function quickPurgeBatch( array $paths ) {
1046  $status = $this->newGood();
1047  $operations = [];
1048  foreach ( $paths as $path ) {
1049  $operations[] = [
1050  'op' => 'delete',
1051  'src' => $this->resolveToStoragePath( $path ),
1052  'ignoreMissingSource' => true
1053  ];
1054  }
1055  $status->merge( $this->backend->doQuickOperations( $operations ) );
1056 
1057  return $status;
1058  }
1059 
1070  public function storeTemp( $originalName, $srcPath ) {
1071  $this->assertWritableRepo(); // fail out if read-only
1072 
1073  $date = MWTimestamp::getInstance()->format( 'YmdHis' );
1074  $hashPath = $this->getHashPath( $originalName );
1075  $dstUrlRel = $hashPath . $date . '!' . rawurlencode( $originalName );
1076  $virtualUrl = $this->getVirtualUrl( 'temp' ) . '/' . $dstUrlRel;
1077 
1078  $result = $this->quickImport( $srcPath, $virtualUrl );
1079  $result->value = $virtualUrl;
1080 
1081  return $result;
1082  }
1083 
1090  public function freeTemp( $virtualUrl ) {
1091  $this->assertWritableRepo(); // fail out if read-only
1092 
1093  $temp = $this->getVirtualUrl( 'temp' );
1094  if ( substr( $virtualUrl, 0, strlen( $temp ) ) != $temp ) {
1095  wfDebug( __METHOD__ . ": Invalid temp virtual URL\n" );
1096 
1097  return false;
1098  }
1099 
1100  return $this->quickPurge( $virtualUrl )->isOK();
1101  }
1102 
1112  public function concatenate( array $srcPaths, $dstPath, $flags = 0 ) {
1113  $this->assertWritableRepo(); // fail out if read-only
1114 
1115  $status = $this->newGood();
1116 
1117  $sources = [];
1118  foreach ( $srcPaths as $srcPath ) {
1119  // Resolve source to a storage path if virtual
1120  $source = $this->resolveToStoragePath( $srcPath );
1121  $sources[] = $source; // chunk to merge
1122  }
1123 
1124  // Concatenate the chunks into one FS file
1125  $params = [ 'srcs' => $sources, 'dst' => $dstPath ];
1126  $status->merge( $this->backend->concatenate( $params ) );
1127  if ( !$status->isOK() ) {
1128  return $status;
1129  }
1130 
1131  // Delete the sources if required
1132  if ( $flags & self::DELETE_SOURCE ) {
1133  $status->merge( $this->quickPurgeBatch( $srcPaths ) );
1134  }
1135 
1136  // Make sure status is OK, despite any quickPurgeBatch() fatals
1137  $status->setResult( true );
1138 
1139  return $status;
1140  }
1141 
1161  public function publish(
1162  $src, $dstRel, $archiveRel, $flags = 0, array $options = []
1163  ) {
1164  $this->assertWritableRepo(); // fail out if read-only
1165 
1166  $status = $this->publishBatch(
1167  [ [ $src, $dstRel, $archiveRel, $options ] ], $flags );
1168  if ( $status->successCount == 0 ) {
1169  $status->setOK( false );
1170  }
1171  if ( isset( $status->value[0] ) ) {
1172  $status->value = $status->value[0];
1173  } else {
1174  $status->value = false;
1175  }
1176 
1177  return $status;
1178  }
1179 
1190  public function publishBatch( array $ntuples, $flags = 0 ) {
1191  $this->assertWritableRepo(); // fail out if read-only
1192 
1193  $backend = $this->backend; // convenience
1194  // Try creating directories
1195  $status = $this->initZones( 'public' );
1196  if ( !$status->isOK() ) {
1197  return $status;
1198  }
1199 
1200  $status = $this->newGood( [] );
1201 
1202  $operations = [];
1203  $sourceFSFilesToDelete = []; // cleanup for disk source files
1204  // Validate each triplet and get the store operation...
1205  foreach ( $ntuples as $ntuple ) {
1206  list( $src, $dstRel, $archiveRel ) = $ntuple;
1207  $srcPath = ( $src instanceof FSFile ) ? $src->getPath() : $src;
1208 
1209  $options = isset( $ntuple[3] ) ? $ntuple[3] : [];
1210  // Resolve source to a storage path if virtual
1211  $srcPath = $this->resolveToStoragePath( $srcPath );
1212  if ( !$this->validateFilename( $dstRel ) ) {
1213  throw new MWException( 'Validation error in $dstRel' );
1214  }
1215  if ( !$this->validateFilename( $archiveRel ) ) {
1216  throw new MWException( 'Validation error in $archiveRel' );
1217  }
1218 
1219  $publicRoot = $this->getZonePath( 'public' );
1220  $dstPath = "$publicRoot/$dstRel";
1221  $archivePath = "$publicRoot/$archiveRel";
1222 
1223  $dstDir = dirname( $dstPath );
1224  $archiveDir = dirname( $archivePath );
1225  // Abort immediately on directory creation errors since they're likely to be repetitive
1226  if ( !$this->initDirectory( $dstDir )->isOK() ) {
1227  return $this->newFatal( 'directorycreateerror', $dstDir );
1228  }
1229  if ( !$this->initDirectory( $archiveDir )->isOK() ) {
1230  return $this->newFatal( 'directorycreateerror', $archiveDir );
1231  }
1232 
1233  // Set any desired headers to be use in GET/HEAD responses
1234  $headers = isset( $options['headers'] ) ? $options['headers'] : [];
1235 
1236  // Archive destination file if it exists.
1237  // This will check if the archive file also exists and fail if does.
1238  // This is a sanity check to avoid data loss. On Windows and Linux,
1239  // copy() will overwrite, so the existence check is vulnerable to
1240  // race conditions unless a functioning LockManager is used.
1241  // LocalFile also uses SELECT FOR UPDATE for synchronization.
1242  $operations[] = [
1243  'op' => 'copy',
1244  'src' => $dstPath,
1245  'dst' => $archivePath,
1246  'ignoreMissingSource' => true
1247  ];
1248 
1249  // Copy (or move) the source file to the destination
1250  if ( FileBackend::isStoragePath( $srcPath ) ) {
1251  if ( $flags & self::DELETE_SOURCE ) {
1252  $operations[] = [
1253  'op' => 'move',
1254  'src' => $srcPath,
1255  'dst' => $dstPath,
1256  'overwrite' => true, // replace current
1257  'headers' => $headers
1258  ];
1259  } else {
1260  $operations[] = [
1261  'op' => 'copy',
1262  'src' => $srcPath,
1263  'dst' => $dstPath,
1264  'overwrite' => true, // replace current
1265  'headers' => $headers
1266  ];
1267  }
1268  } else { // FS source path
1269  $operations[] = [
1270  'op' => 'store',
1271  'src' => $src, // prefer FSFile objects
1272  'dst' => $dstPath,
1273  'overwrite' => true, // replace current
1274  'headers' => $headers
1275  ];
1276  if ( $flags & self::DELETE_SOURCE ) {
1277  $sourceFSFilesToDelete[] = $srcPath;
1278  }
1279  }
1280  }
1281 
1282  // Execute the operations for each triplet
1283  $status->merge( $backend->doOperations( $operations ) );
1284  // Find out which files were archived...
1285  foreach ( $ntuples as $i => $ntuple ) {
1286  list( , , $archiveRel ) = $ntuple;
1287  $archivePath = $this->getZonePath( 'public' ) . "/$archiveRel";
1288  if ( $this->fileExists( $archivePath ) ) {
1289  $status->value[$i] = 'archived';
1290  } else {
1291  $status->value[$i] = 'new';
1292  }
1293  }
1294  // Cleanup for disk source files...
1295  foreach ( $sourceFSFilesToDelete as $file ) {
1296  MediaWiki\suppressWarnings();
1297  unlink( $file ); // FS cleanup
1298  MediaWiki\restoreWarnings();
1299  }
1300 
1301  return $status;
1302  }
1303 
1311  protected function initDirectory( $dir ) {
1312  $path = $this->resolveToStoragePath( $dir );
1313  list( , $container, ) = FileBackend::splitStoragePath( $path );
1314 
1315  $params = [ 'dir' => $path ];
1316  if ( $this->isPrivate
1317  || $container === $this->zones['deleted']['container']
1318  || $container === $this->zones['temp']['container']
1319  ) {
1320  # Take all available measures to prevent web accessibility of new deleted
1321  # directories, in case the user has not configured offline storage
1322  $params = [ 'noAccess' => true, 'noListing' => true ] + $params;
1323  }
1324 
1325  $status = $this->newGood();
1326  $status->merge( $this->backend->prepare( $params ) );
1327 
1328  return $status;
1329  }
1330 
1337  public function cleanDir( $dir ) {
1338  $this->assertWritableRepo(); // fail out if read-only
1339 
1340  $status = $this->newGood();
1341  $status->merge( $this->backend->clean(
1342  [ 'dir' => $this->resolveToStoragePath( $dir ) ] ) );
1343 
1344  return $status;
1345  }
1346 
1353  public function fileExists( $file ) {
1354  $result = $this->fileExistsBatch( [ $file ] );
1355 
1356  return $result[0];
1357  }
1358 
1365  public function fileExistsBatch( array $files ) {
1366  $paths = array_map( [ $this, 'resolveToStoragePath' ], $files );
1367  $this->backend->preloadFileStat( [ 'srcs' => $paths ] );
1368 
1369  $result = [];
1370  foreach ( $files as $key => $file ) {
1371  $path = $this->resolveToStoragePath( $file );
1372  $result[$key] = $this->backend->fileExists( [ 'src' => $path ] );
1373  }
1374 
1375  return $result;
1376  }
1377 
1388  public function delete( $srcRel, $archiveRel ) {
1389  $this->assertWritableRepo(); // fail out if read-only
1390 
1391  return $this->deleteBatch( [ [ $srcRel, $archiveRel ] ] );
1392  }
1393 
1411  public function deleteBatch( array $sourceDestPairs ) {
1412  $this->assertWritableRepo(); // fail out if read-only
1413 
1414  // Try creating directories
1415  $status = $this->initZones( [ 'public', 'deleted' ] );
1416  if ( !$status->isOK() ) {
1417  return $status;
1418  }
1419 
1420  $status = $this->newGood();
1421 
1422  $backend = $this->backend; // convenience
1423  $operations = [];
1424  // Validate filenames and create archive directories
1425  foreach ( $sourceDestPairs as $pair ) {
1426  list( $srcRel, $archiveRel ) = $pair;
1427  if ( !$this->validateFilename( $srcRel ) ) {
1428  throw new MWException( __METHOD__ . ':Validation error in $srcRel' );
1429  } elseif ( !$this->validateFilename( $archiveRel ) ) {
1430  throw new MWException( __METHOD__ . ':Validation error in $archiveRel' );
1431  }
1432 
1433  $publicRoot = $this->getZonePath( 'public' );
1434  $srcPath = "{$publicRoot}/$srcRel";
1435 
1436  $deletedRoot = $this->getZonePath( 'deleted' );
1437  $archivePath = "{$deletedRoot}/{$archiveRel}";
1438  $archiveDir = dirname( $archivePath ); // does not touch FS
1439 
1440  // Create destination directories
1441  if ( !$this->initDirectory( $archiveDir )->isOK() ) {
1442  return $this->newFatal( 'directorycreateerror', $archiveDir );
1443  }
1444 
1445  $operations[] = [
1446  'op' => 'move',
1447  'src' => $srcPath,
1448  'dst' => $archivePath,
1449  // We may have 2+ identical files being deleted,
1450  // all of which will map to the same destination file
1451  'overwriteSame' => true // also see T33792
1452  ];
1453  }
1454 
1455  // Move the files by execute the operations for each pair.
1456  // We're now committed to returning an OK result, which will
1457  // lead to the files being moved in the DB also.
1458  $opts = [ 'force' => true ];
1459  $status->merge( $backend->doOperations( $operations, $opts ) );
1460 
1461  return $status;
1462  }
1463 
1470  public function cleanupDeletedBatch( array $storageKeys ) {
1471  $this->assertWritableRepo();
1472  }
1473 
1482  public function getDeletedHashPath( $key ) {
1483  if ( strlen( $key ) < 31 ) {
1484  throw new MWException( "Invalid storage key '$key'." );
1485  }
1486  $path = '';
1487  for ( $i = 0; $i < $this->deletedHashLevels; $i++ ) {
1488  $path .= $key[$i] . '/';
1489  }
1490 
1491  return $path;
1492  }
1493 
1502  protected function resolveToStoragePath( $path ) {
1503  if ( $this->isVirtualUrl( $path ) ) {
1504  return $this->resolveVirtualUrl( $path );
1505  }
1506 
1507  return $path;
1508  }
1509 
1517  public function getLocalCopy( $virtualUrl ) {
1518  $path = $this->resolveToStoragePath( $virtualUrl );
1519 
1520  return $this->backend->getLocalCopy( [ 'src' => $path ] );
1521  }
1522 
1531  public function getLocalReference( $virtualUrl ) {
1532  $path = $this->resolveToStoragePath( $virtualUrl );
1533 
1534  return $this->backend->getLocalReference( [ 'src' => $path ] );
1535  }
1536 
1544  public function getFileProps( $virtualUrl ) {
1545  $fsFile = $this->getLocalReference( $virtualUrl );
1546  $mwProps = new MWFileProps( MimeMagic::singleton() );
1547  if ( $fsFile ) {
1548  $props = $mwProps->getPropsFromPath( $fsFile->getPath(), true );
1549  } else {
1550  $props = $mwProps->newPlaceholderProps();
1551  }
1552 
1553  return $props;
1554  }
1555 
1562  public function getFileTimestamp( $virtualUrl ) {
1563  $path = $this->resolveToStoragePath( $virtualUrl );
1564 
1565  return $this->backend->getFileTimestamp( [ 'src' => $path ] );
1566  }
1567 
1574  public function getFileSize( $virtualUrl ) {
1575  $path = $this->resolveToStoragePath( $virtualUrl );
1576 
1577  return $this->backend->getFileSize( [ 'src' => $path ] );
1578  }
1579 
1586  public function getFileSha1( $virtualUrl ) {
1587  $path = $this->resolveToStoragePath( $virtualUrl );
1588 
1589  return $this->backend->getFileSha1Base36( [ 'src' => $path ] );
1590  }
1591 
1601  public function streamFileWithStatus( $virtualUrl, $headers = [], $optHeaders = [] ) {
1602  $path = $this->resolveToStoragePath( $virtualUrl );
1603  $params = [ 'src' => $path, 'headers' => $headers, 'options' => $optHeaders ];
1604 
1605  // T172851: HHVM does not flush the output properly, causing OOM
1606  ob_start( null, 1048576 );
1607  ob_implicit_flush( true );
1608 
1609  $status = $this->newGood();
1610  $status->merge( $this->backend->streamFile( $params ) );
1611 
1612  ob_end_flush();
1613 
1614  return $status;
1615  }
1616 
1625  public function streamFile( $virtualUrl, $headers = [] ) {
1626  return $this->streamFileWithStatus( $virtualUrl, $headers )->isOK();
1627  }
1628 
1637  public function enumFiles( $callback ) {
1638  $this->enumFilesInStorage( $callback );
1639  }
1640 
1648  protected function enumFilesInStorage( $callback ) {
1649  $publicRoot = $this->getZonePath( 'public' );
1650  $numDirs = 1 << ( $this->hashLevels * 4 );
1651  // Use a priori assumptions about directory structure
1652  // to reduce the tree height of the scanning process.
1653  for ( $flatIndex = 0; $flatIndex < $numDirs; $flatIndex++ ) {
1654  $hexString = sprintf( "%0{$this->hashLevels}x", $flatIndex );
1655  $path = $publicRoot;
1656  for ( $hexPos = 0; $hexPos < $this->hashLevels; $hexPos++ ) {
1657  $path .= '/' . substr( $hexString, 0, $hexPos + 1 );
1658  }
1659  $iterator = $this->backend->getFileList( [ 'dir' => $path ] );
1660  foreach ( $iterator as $name ) {
1661  // Each item returned is a public file
1662  call_user_func( $callback, "{$path}/{$name}" );
1663  }
1664  }
1665  }
1666 
1673  public function validateFilename( $filename ) {
1674  if ( strval( $filename ) == '' ) {
1675  return false;
1676  }
1677 
1678  return FileBackend::isPathTraversalFree( $filename );
1679  }
1680 
1687  switch ( $this->pathDisclosureProtection ) {
1688  case 'none':
1689  case 'simple': // b/c
1690  $callback = [ $this, 'passThrough' ];
1691  break;
1692  default: // 'paranoid'
1693  $callback = [ $this, 'paranoidClean' ];
1694  }
1695  return $callback;
1696  }
1697 
1704  function paranoidClean( $param ) {
1705  return '[hidden]';
1706  }
1707 
1714  function passThrough( $param ) {
1715  return $param;
1716  }
1717 
1724  public function newFatal( $message /*, parameters...*/ ) {
1725  $status = call_user_func_array( [ 'Status', 'newFatal' ], func_get_args() );
1726  $status->cleanCallback = $this->getErrorCleanupFunction();
1727 
1728  return $status;
1729  }
1730 
1737  public function newGood( $value = null ) {
1739  $status->cleanCallback = $this->getErrorCleanupFunction();
1740 
1741  return $status;
1742  }
1743 
1752  public function checkRedirect( Title $title ) {
1753  return false;
1754  }
1755 
1763  public function invalidateImageRedirect( Title $title ) {
1764  }
1765 
1771  public function getDisplayName() {
1773 
1774  if ( $this->isLocal() ) {
1775  return $wgSitename;
1776  }
1777 
1778  // 'shared-repo-name-wikimediacommons' is used when $wgUseInstantCommons = true
1779  return wfMessageFallback( 'shared-repo-name-' . $this->name, 'shared-repo' )->text();
1780  }
1781 
1789  public function nameForThumb( $name ) {
1790  if ( strlen( $name ) > $this->abbrvThreshold ) {
1792  $name = ( $ext == '' ) ? 'thumbnail' : "thumbnail.$ext";
1793  }
1794 
1795  return $name;
1796  }
1797 
1803  public function isLocal() {
1804  return $this->getName() == 'local';
1805  }
1806 
1815  public function getSharedCacheKey( /*...*/ ) {
1816  return false;
1817  }
1818 
1826  public function getLocalCacheKey( /*...*/ ) {
1827  $args = func_get_args();
1828  array_unshift( $args, 'filerepo', $this->getName() );
1829 
1830  return call_user_func_array( 'wfMemcKey', $args );
1831  }
1832 
1841  public function getTempRepo() {
1842  return new TempFileRepo( [
1843  'name' => "{$this->name}-temp",
1844  'backend' => $this->backend,
1845  'zones' => [
1846  'public' => [
1847  // Same place storeTemp() uses in the base repo, though
1848  // the path hashing is mismatched, which is annoying.
1849  'container' => $this->zones['temp']['container'],
1850  'directory' => $this->zones['temp']['directory']
1851  ],
1852  'thumb' => [
1853  'container' => $this->zones['temp']['container'],
1854  'directory' => $this->zones['temp']['directory'] == ''
1855  ? 'thumb'
1856  : $this->zones['temp']['directory'] . '/thumb'
1857  ],
1858  'transcoded' => [
1859  'container' => $this->zones['temp']['container'],
1860  'directory' => $this->zones['temp']['directory'] == ''
1861  ? 'transcoded'
1862  : $this->zones['temp']['directory'] . '/transcoded'
1863  ]
1864  ],
1865  'hashLevels' => $this->hashLevels, // performance
1866  'isPrivate' => true // all in temp zone
1867  ] );
1868  }
1869 
1876  public function getUploadStash( User $user = null ) {
1877  return new UploadStash( $this, $user );
1878  }
1879 
1887  protected function assertWritableRepo() {
1888  }
1889 
1896  public function getInfo() {
1897  $ret = [
1898  'name' => $this->getName(),
1899  'displayname' => $this->getDisplayName(),
1900  'rootUrl' => $this->getZoneUrl( 'public' ),
1901  'local' => $this->isLocal(),
1902  ];
1903 
1904  $optionalSettings = [
1905  'url', 'thumbUrl', 'initialCapital', 'descBaseUrl', 'scriptDirUrl', 'articleUrl',
1906  'fetchDescription', 'descriptionCacheExpiry', 'scriptExtension', 'favicon'
1907  ];
1908  foreach ( $optionalSettings as $k ) {
1909  if ( isset( $this->$k ) ) {
1910  $ret[$k] = $this->$k;
1911  }
1912  }
1913 
1914  return $ret;
1915  }
1916 
1921  public function hasSha1Storage() {
1922  return $this->hasSha1Storage;
1923  }
1924 
1929  public function supportsSha1URLs() {
1930  return $this->supportsSha1URLs;
1931  }
1932 }
initZones($doZones=[])
Check if a single zone or list of zones is defined for usage.
Definition: FileRepo.php:236
string $favicon
The URL of the repo's favicon, if any.
Definition: FileRepo.php:121
assertWritableRepo()
Throw an exception if this repo is read-only by design.
Definition: FileRepo.php:1887
getHashPath($name)
Get a relative path including trailing slash, e.g.
Definition: FileRepo.php:659
bool $fetchDescription
Whether to fetch commons image description pages and display them on the local wiki.
Definition: FileRepo.php:47
string $scriptDirUrl
URL of the MediaWiki installation, equivalent to $wgScriptPath, e.g.
Definition: FileRepo.php:79
static normalizeTitle($title, $exception=false)
Given a string or Title object return either a valid Title object with namespace NS_FILE or null...
Definition: File.php:184
deferred txt A few of the database updates required by various functions here can be deferred until after the result page is displayed to the user For updating the view updating the linked to tables after a etc PHP does not yet have any way to tell the server to actually return and disconnect while still running these but it might have such a feature in the future We handle these by creating a deferred update object and putting those objects on a global list
Definition: deferred.txt:11
int $abbrvThreshold
File names over this size will use the short form of thumbnail names.
Definition: FileRepo.php:118
getVirtualUrl($suffix=false)
Get a URL referring to this repository, with the private mwrepo protocol.
Definition: FileRepo.php:266
enumFiles($callback)
Call a callback function for every public regular file in the repository.
Definition: FileRepo.php:1637
the array() calling protocol came about after MediaWiki 1.4rc1.
array $zones
Map of zones to config.
Definition: FileRepo.php:62
static getHashPathForLevel($name, $levels)
Definition: FileRepo.php:681
null for the local wiki Added should default to null in handler for backwards compatibility add a value to it if you want to add a cookie that have to vary cache options can modify $query
Definition: hooks.txt:1582
canTransformVia404()
Returns true if the repository can transform files via a 404 handler.
Definition: FileRepo.php:619
getTempRepo()
Get a temporary private FileRepo associated with this repo.
Definition: FileRepo.php:1841
magic word the default is to use $key to get the and $key value or $key value text $key value html to format the value $key
Definition: hooks.txt:2556
doOperations(array $ops, array $opts=[])
This is the main entry point into the backend for write operations.
getUserCaseDBKey()
Get the DB key with the initial letter case as specified by the user.
Definition: Title.php:965
string $pathDisclosureProtection
May be 'paranoid' to remove all parameters from error messages, 'none' to leave the paths in unchange...
Definition: FileRepo.php:100
$wgSitename
Name of the site.
getRootDirectory()
Get the public zone root storage directory of the repository.
Definition: FileRepo.php:648
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses & $ret
Definition: hooks.txt:1966
getUploadStash(User $user=null)
Get an UploadStash associated with this repo.
Definition: FileRepo.php:1876
streamFile($virtualUrl, $headers=[])
Attempt to stream a file with the given virtual URL/storage path.
Definition: FileRepo.php:1625
quickPurge($path)
Purge a file from the repo.
Definition: FileRepo.php:969
static singleton()
Get an instance of this class.
Definition: MimeMagic.php:33
if(!isset($args[0])) $lang
string false $url
Public zone URL.
Definition: FileRepo.php:103
const DELETE_SOURCE
Definition: FileRepo.php:38
passThrough($param)
Path disclosure protection function.
Definition: FileRepo.php:1714
resolveToStoragePath($path)
If a path is a virtual URL, resolve it to a storage path.
Definition: FileRepo.php:1502
getZoneLocation($zone)
The the storage container and base path of a zone.
Definition: FileRepo.php:349
checkRedirect(Title $title)
Checks if there is a redirect named as $title.
Definition: FileRepo.php:1752
$source
$value
getLocalCacheKey()
Get a key for this repo in the local cache domain.
Definition: FileRepo.php:1826
getLocalCopy($virtualUrl)
Get a local FS copy of a file with a given virtual URL/storage path.
Definition: FileRepo.php:1517
getDescriptionRenderUrl($name, $lang=null)
Get the URL of the content-only fragment of the description page.
Definition: FileRepo.php:776
static isVirtualUrl($url)
Determine if a string is an mwrepo:// URL.
Definition: FileRepo.php:254
wfMessageFallback()
This function accepts multiple message keys and returns a message instance for the first message whic...
it s the revision text itself In either if gzip is the revision text is gzipped $flags
Definition: hooks.txt:2803
initDirectory($dir)
Creates a directory with the appropriate zone permissions.
Definition: FileRepo.php:1311
getHashLevels()
Get the number of hash directory levels.
Definition: FileRepo.php:700
store($srcPath, $dstZone, $dstRel, $flags=0)
Store a file to a given destination.
Definition: FileRepo.php:823
wfUrlencode($s)
We want some things to be included as literal characters in our title URLs for prettiness, which urlencode encodes by default.
resolveVirtualUrl($url)
Get the backend storage path corresponding to a virtual URL.
Definition: FileRepo.php:323
when a variable name is used in a it is silently declared as a new local masking the global
Definition: design.txt:93
freeTemp($virtualUrl)
Remove a temporary file or mark it for garbage collection.
Definition: FileRepo.php:1090
static extensionFromPath($path, $case= 'lowercase')
Get the final extension from a storage or FS path.
getTempHashPath($suffix)
Get a relative path including trailing slash, e.g.
Definition: FileRepo.php:670
paranoidClean($param)
Path disclosure protection function.
Definition: FileRepo.php:1704
wfDebug($text, $dest= 'all', array $context=[])
Sends a line to the debug log if enabled or, optionally, to a comment in output.
cleanupDeletedBatch(array $storageKeys)
Delete files in the deleted directory if they are not referenced in the filearchive table...
Definition: FileRepo.php:1470
const DELETED_FILE
Definition: File.php:53
getBackend()
Get the file backend instance.
Definition: FileRepo.php:215
The index of the header message $result[1]=The index of the body text message $result[2 through n]=Parameters passed to body text message.Please note the header message cannot receive/use parameters. 'ImportHandleLogItemXMLTag':When parsing a XML tag in a log item.Return false to stop further processing of the tag $reader:XMLReader object $logInfo:Array of information 'ImportHandlePageXMLTag':When parsing a XML tag in a page.Return false to stop further processing of the tag $reader:XMLReader object &$pageInfo:Array of information 'ImportHandleRevisionXMLTag':When parsing a XML tag in a page revision.Return false to stop further processing of the tag $reader:XMLReader object $pageInfo:Array of page information $revisionInfo:Array of revision information 'ImportHandleToplevelXMLTag':When parsing a top level XML tag.Return false to stop further processing of the tag $reader:XMLReader object 'ImportHandleUploadXMLTag':When parsing a XML tag in a file upload.Return false to stop further processing of the tag $reader:XMLReader object $revisionInfo:Array of information 'ImportLogInterwikiLink':Hook to change the interwiki link used in log entries and edit summaries for transwiki imports.&$fullInterwikiPrefix:Interwiki prefix, may contain colons.&$pageTitle:String that contains page title. 'ImportSources':Called when reading from the $wgImportSources configuration variable.Can be used to lazy-load the import sources list.&$importSources:The value of $wgImportSources.Modify as necessary.See the comment in DefaultSettings.php for the detail of how to structure this array. 'InfoAction':When building information to display on the action=info page.$context:IContextSource object &$pageInfo:Array of information 'InitializeArticleMaybeRedirect':MediaWiki check to see if title is a redirect.&$title:Title object for the current page &$request:WebRequest &$ignoreRedirect:boolean to skip redirect check &$target:Title/string of redirect target &$article:Article object 'InternalParseBeforeLinks':during Parser's internalParse method before links but after nowiki/noinclude/includeonly/onlyinclude and other processings.&$parser:Parser object &$text:string containing partially parsed text &$stripState:Parser's internal StripState object 'InternalParseBeforeSanitize':during Parser's internalParse method just before the parser removes unwanted/dangerous HTML tags and after nowiki/noinclude/includeonly/onlyinclude and other processings.Ideal for syntax-extensions after template/parser function execution which respect nowiki and HTML-comments.&$parser:Parser object &$text:string containing partially parsed text &$stripState:Parser's internal StripState object 'InterwikiLoadPrefix':When resolving if a given prefix is an interwiki or not.Return true without providing an interwiki to continue interwiki search.$prefix:interwiki prefix we are looking for.&$iwData:output array describing the interwiki with keys iw_url, iw_local, iw_trans and optionally iw_api and iw_wikiid. 'InvalidateEmailComplete':Called after a user's email has been invalidated successfully.$user:user(object) whose email is being invalidated 'IRCLineURL':When constructing the URL to use in an IRC notification.Callee may modify $url and $query, URL will be constructed as $url.$query &$url:URL to index.php &$query:Query string $rc:RecentChange object that triggered url generation 'IsFileCacheable':Override the result of Article::isFileCacheable()(if true) &$article:article(object) being checked 'IsTrustedProxy':Override the result of IP::isTrustedProxy() &$ip:IP being check &$result:Change this value to override the result of IP::isTrustedProxy() 'IsUploadAllowedFromUrl':Override the result of UploadFromUrl::isAllowedUrl() $url:URL used to upload from &$allowed:Boolean indicating if uploading is allowed for given URL 'isValidEmailAddr':Override the result of Sanitizer::validateEmail(), for instance to return false if the domain name doesn't match your organization.$addr:The e-mail address entered by the user &$result:Set this and return false to override the internal checks 'isValidPassword':Override the result of User::isValidPassword() $password:The password entered by the user &$result:Set this and return false to override the internal checks $user:User the password is being validated for 'Language::getMessagesFileName':$code:The language code or the language we're looking for a messages file for &$file:The messages file path, you can override this to change the location. 'LanguageGetMagic':DEPRECATED!Use $magicWords in a file listed in $wgExtensionMessagesFiles instead.Use this to define synonyms of magic words depending of the language &$magicExtensions:associative array of magic words synonyms $lang:language code(string) 'LanguageGetNamespaces':Provide custom ordering for namespaces or remove namespaces.Do not use this hook to add namespaces.Use CanonicalNamespaces for that.&$namespaces:Array of namespaces indexed by their numbers 'LanguageGetSpecialPageAliases':DEPRECATED!Use $specialPageAliases in a file listed in $wgExtensionMessagesFiles instead.Use to define aliases of special pages names depending of the language &$specialPageAliases:associative array of magic words synonyms $lang:language code(string) 'LanguageGetTranslatedLanguageNames':Provide translated language names.&$names:array of language code=> language name $code:language of the preferred translations 'LanguageLinks':Manipulate a page's language links.This is called in various places to allow extensions to define the effective language links for a page.$title:The page's Title.&$links:Array with elements of the form"language:title"in the order that they will be output.&$linkFlags:Associative array mapping prefixed links to arrays of flags.Currently unused, but planned to provide support for marking individual language links in the UI, e.g.for featured articles. 'LanguageSelector':Hook to change the language selector available on a page.$out:The output page.$cssClassName:CSS class name of the language selector. 'LinkBegin':DEPRECATED!Use HtmlPageLinkRendererBegin instead.Used when generating internal and interwiki links in Linker::link(), before processing starts.Return false to skip default processing and return $ret.See documentation for Linker::link() for details on the expected meanings of parameters.$skin:the Skin object $target:the Title that the link is pointing to &$html:the contents that the< a > tag should have(raw HTML) $result
Definition: hooks.txt:1964
if($line===false) $args
Definition: cdb.php:63
static isCapitalized($index)
Is the namespace first-letter capitalized?
makeUrl($query= '', $entry= 'index')
Make an url to this repo.
Definition: FileRepo.php:720
getFileTimestamp($virtualUrl)
Get the timestamp of a file with a given virtual URL/storage path.
Definition: FileRepo.php:1562
array $oldFileFactoryKey
callable|bool Override these in the base class
Definition: FileRepo.php:133
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses just before the function returns a value If you return true
Definition: hooks.txt:1966
const OVERWRITE
Definition: FileRepo.php:39
getFileSha1($virtualUrl)
Get the sha1 (base 36) of a file with a given virtual URL/storage path.
Definition: FileRepo.php:1586
string $scriptExtension
Script extension of the MediaWiki installation, equivalent to the old $wgScriptExtension, e.g.
Definition: FileRepo.php:83
isLocal()
Returns true if this the local file repository.
Definition: FileRepo.php:1803
getReadOnlyReason()
Get an explanatory message if this repo is read-only.
Definition: FileRepo.php:225
getInfo()
Return information about the repository.
Definition: FileRepo.php:1896
wfAppendQuery($url, $query)
Append a query string to an existing URL, which may or may not already have query string parameters a...
string $thumbScriptUrl
URL of thumb.php.
Definition: FileRepo.php:65
getDescriptionStylesheetUrl()
Get the URL of the stylesheet to apply to description pages.
Definition: FileRepo.php:801
getDBkey()
Get the main part with underscores.
Definition: Title.php:956
quickPurgeBatch(array $paths)
Purge a batch of files from the repo.
Definition: FileRepo.php:1045
storeTemp($originalName, $srcPath)
Pick a random name in the temp zone and store a file to it.
Definition: FileRepo.php:1070
getErrorCleanupFunction()
Get a callback function to use for cleaning error message parameters.
Definition: FileRepo.php:1686
static getInstance($ts=false)
Get a timestamp instance in GMT.
Definition: MWTimestamp.php:39
invalidateImageRedirect(Title $title)
Invalidates image redirect cache related to that image Doesn't do anything for repositories that don'...
Definition: FileRepo.php:1763
static isStoragePath($path)
Check if a given path is a "mwstore://" path.
concatenate(array $srcPaths, $dstPath, $flags=0)
Concatenate a list of temporary files into a target file location.
Definition: FileRepo.php:1112
deleteBatch(array $sourceDestPairs)
Move a group of files to the deletion archive.
Definition: FileRepo.php:1411
int $hashLevels
The number of directory levels for hash-based division of files.
Definition: FileRepo.php:109
getThumbScriptUrl()
Get the URL of thumb.php.
Definition: FileRepo.php:610
bool $initialCapital
Equivalent to $wgCapitalLinks (or $wgCapitalLinkOverrides[NS_FILE], determines whether filenames impl...
Definition: FileRepo.php:93
newFile($title, $time=false)
Create a new File object from the local repository.
Definition: FileRepo.php:387
getSharedCacheKey()
Get a key on the primary cache for this repository.
Definition: FileRepo.php:1815
nameForThumb($name)
Get the portion of the file that contains the origin file name.
Definition: FileRepo.php:1789
$params
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped & $options
Definition: hooks.txt:1966
string $articleUrl
Equivalent to $wgArticlePath, e.g.
Definition: FileRepo.php:86
string $thumbUrl
The base thumbnail URL.
Definition: FileRepo.php:106
findFile($title, $options=[])
Find an instance of the named file created at the specified time Returns false if the file does not e...
Definition: FileRepo.php:420
quickImport($src, $dst, $options=null)
Import a file from the local file system into the repo.
Definition: FileRepo.php:957
const ATTR_UNICODE_PATHS
validateFilename($filename)
Determine if a relative path is valid, i.e.
Definition: FileRepo.php:1673
const SKIP_LOCKING
Definition: FileRepo.php:41
namespace and then decline to actually register it file or subcat img or subcat $title
Definition: hooks.txt:933
findFiles(array $items, $flags=0)
Find many files at once.
Definition: FileRepo.php:496
static newGood($value=null)
Factory function for good results.
Definition: StatusValue.php:81
fileExists($file)
Checks existence of a a file.
Definition: FileRepo.php:1353
const NS_FILE
Definition: Defines.php:71
findFileFromKey($sha1, $options=[])
Find an instance of the file with this key, created at the specified time Returns false if the file d...
Definition: FileRepo.php:533
bool $hasSha1Storage
Definition: FileRepo.php:53
int $descriptionCacheExpiry
Definition: FileRepo.php:50
cleanDir($dir)
Deletes a directory if empty.
Definition: FileRepo.php:1337
string $descBaseUrl
URL of image description pages, e.g.
Definition: FileRepo.php:74
This document is intended to provide useful advice for parties seeking to redistribute MediaWiki to end users It s targeted particularly at maintainers for Linux since it s been observed that distribution packages of MediaWiki often break We ve consistently had to recommend that users seeking support use official tarballs instead of their distribution s and this often solves whatever problem the user is having It would be nice if this could such as
Definition: distributors.txt:9
getFileProps($virtualUrl)
Get properties of a file with a given virtual URL/storage path.
Definition: FileRepo.php:1544
getNameFromTitle(Title $title)
Get the name of a file from its title object.
Definition: FileRepo.php:629
const NAME_AND_TIME_ONLY
Definition: FileRepo.php:43
getDescriptionUrl($name)
Get the URL of an image description page.
Definition: FileRepo.php:742
findFilesByPrefix($prefix, $limit)
Return an array of files where the name starts with $prefix.
Definition: FileRepo.php:601
backendSupportsUnicodePaths()
Definition: FileRepo.php:311
injection txt This is an overview of how MediaWiki makes use of dependency injection The design described here grew from the discussion of RFC T384 The term dependency this means that anything an object needs to operate should be injected from the the object itself should only know narrow no concrete implementation of the logic it relies on The requirement to inject everything typically results in an architecture that based on two main types of and essentially stateless service objects that use other service objects to operate on the value objects As of the beginning MediaWiki is only starting to use the DI approach Much of the code still relies on global state or direct resulting in a highly cyclical dependency which acts as the top level factory for services in MediaWiki which can be used to gain access to default instances of various services MediaWikiServices however also allows new services to be defined and default services to be redefined Services are defined or redefined by providing a callback the instantiator that will return a new instance of the service When it will create an instance of MediaWikiServices and populate it with the services defined in the files listed by thereby bootstrapping the DI framework Per $wgServiceWiringFiles lists includes ServiceWiring php
Definition: injection.txt:35
UploadStash is intended to accomplish a few things:
Definition: UploadStash.php:54
cleanupBatch(array $files, $flags=0)
Deletes a batch of files.
Definition: FileRepo.php:917
bool $transformVia404
Whether to skip media file transformation on parse and rely on a 404 handler instead.
Definition: FileRepo.php:69
findBySha1s(array $hashes)
Get an array of arrays or iterators of file objects for files that have the given SHA-1 content hashe...
Definition: FileRepo.php:581
getFileSize($virtualUrl)
Get the size of a file with a given virtual URL/storage path.
Definition: FileRepo.php:1574
Class representing a non-directory file on the file system.
Definition: FSFile.php:29
const OVERWRITE_SAME
Definition: FileRepo.php:40
getZoneUrl($zone, $ext=null)
Get the URL corresponding to one of the four basic zones.
Definition: FileRepo.php:282
getDeletedHashPath($key)
Get a relative path for a deletion archive key, e.g.
Definition: FileRepo.php:1482
wfArrayToCgi($array1, $array2=null, $prefix= '')
This function takes one or two arrays as input, and returns a CGI-style string, e.g.
newFatal($message)
Create a new fatal error.
Definition: FileRepo.php:1724
design txt This is a brief overview of the new design More thorough and up to date information is available on the documentation wiki at name
Definition: design.txt:12
FileRepo for temporary files created via FileRepo::getTempRepo()
Definition: TempFileRepo.php:5
Base class for all file backend classes (including multi-write backends).
Definition: FileBackend.php:92
getDisplayName()
Get the human-readable name of the repo.
Definition: FileRepo.php:1771
Base class for file repositories.
Definition: FileRepo.php:37
bool $supportsSha1URLs
Definition: FileRepo.php:56
static isPathTraversalFree($path)
Check if a relative path has no directory traversals.
this class mediates it Skin Encapsulates a look and feel for the wiki All of the functions that render HTML and make choices about how to render it are here and are called from various other places when and is meant to be subclassed with other skins that may override some of its functions The User object contains a reference to a and so rather than having a global skin object we just rely on the global User and get the skin with $wgUser and also has some character encoding functions and other locale stuff The current user interface language is instantiated as and the local content language as $wgContLang
Definition: design.txt:56
MimeMagic helper wrapper.
Definition: MWFileProps.php:28
Allows to change the fields on the form that will be generated $name
Definition: hooks.txt:302
array $fileFactoryKey
callable|bool Override these in the base class
Definition: FileRepo.php:131
array $oldFileFactory
callable|bool Override these in the base class
Definition: FileRepo.php:129
array $fileFactory
callable Override these in the base class
Definition: FileRepo.php:127
storeBatch(array $triplets, $flags=0)
Store a batch of files.
Definition: FileRepo.php:846
Status::newGood()`to allow deletion, and then`return false`from the hook function.Ensure you consume the 'ChangeTagAfterDelete'hook to carry out custom deletion actions.$tag:name of the tag $user:user initiating the action &$status:Status object.See above. 'ChangeTagsListActive':Allows you to nominate which of the tags your extension uses are in active use.&$tags:list of all active tags.Append to this array. 'ChangeTagsAfterUpdateTags':Called after tags have been updated with the ChangeTags::updateTags function.Params:$addedTags:tags effectively added in the update $removedTags:tags effectively removed in the update $prevTags:tags that were present prior to the update $rc_id:recentchanges table id $rev_id:revision table id $log_id:logging table id $params:tag params $rc:RecentChange being tagged when the tagging accompanies the action or null $user:User who performed the tagging when the tagging is subsequent to the action or null 'ChangeTagsAllowedAdd':Called when checking if a user can add tags to a change.&$allowedTags:List of all the tags the user is allowed to add.Any tags the user wants to add($addTags) that are not in this array will cause it to fail.You may add or remove tags to this array as required.$addTags:List of tags user intends to add.$user:User who is adding the tags. 'ChangeUserGroups':Called before user groups are changed.$performer:The User who will perform the change $user:The User whose groups will be changed &$add:The groups that will be added &$remove:The groups that will be removed 'Collation::factory':Called if $wgCategoryCollation is an unknown collation.$collationName:Name of the collation in question &$collationObject:Null.Replace with a subclass of the Collation class that implements the collation given in $collationName. 'ConfirmEmailComplete':Called after a user's email has been confirmed successfully.$user:user(object) whose email is being confirmed 'ContentAlterParserOutput':Modify parser output for a given content object.Called by Content::getParserOutput after parsing has finished.Can be used for changes that depend on the result of the parsing but have to be done before LinksUpdate is called(such as adding tracking categories based on the rendered HTML).$content:The Content to render $title:Title of the page, as context $parserOutput:ParserOutput to manipulate 'ContentGetParserOutput':Customize parser output for a given content object, called by AbstractContent::getParserOutput.May be used to override the normal model-specific rendering of page content.$content:The Content to render $title:Title of the page, as context $revId:The revision ID, as context $options:ParserOptions for rendering.To avoid confusing the parser cache, the output can only depend on parameters provided to this hook function, not on global state.$generateHtml:boolean, indicating whether full HTML should be generated.If false, generation of HTML may be skipped, but other information should still be present in the ParserOutput object.&$output:ParserOutput, to manipulate or replace 'ContentHandlerDefaultModelFor':Called when the default content model is determined for a given title.May be used to assign a different model for that title.$title:the Title in question &$model:the model name.Use with CONTENT_MODEL_XXX constants. 'ContentHandlerForModelID':Called when a ContentHandler is requested for a given content model name, but no entry for that model exists in $wgContentHandlers.Note:if your extension implements additional models via this hook, please use GetContentModels hook to make them known to core.$modeName:the requested content model name &$handler:set this to a ContentHandler object, if desired. 'ContentModelCanBeUsedOn':Called to determine whether that content model can be used on a given page.This is especially useful to prevent some content models to be used in some special location.$contentModel:ID of the content model in question $title:the Title in question.&$ok:Output parameter, whether it is OK to use $contentModel on $title.Handler functions that modify $ok should generally return false to prevent further hooks from further modifying $ok. 'ContribsPager::getQueryInfo':Before the contributions query is about to run &$pager:Pager object for contributions &$queryInfo:The query for the contribs Pager 'ContribsPager::reallyDoQuery':Called before really executing the query for My Contributions &$data:an array of results of all contribs queries $pager:The ContribsPager object hooked into $offset:Index offset, inclusive $limit:Exact query limit $descending:Query direction, false for ascending, true for descending 'ContributionsLineEnding':Called before a contributions HTML line is finished $page:SpecialPage object for contributions &$ret:the HTML line $row:the DB row for this line &$classes:the classes to add to the surrounding< li > &$attribs:associative array of other HTML attributes for the< li > element.Currently only data attributes reserved to MediaWiki are allowed(see Sanitizer::isReservedDataAttribute). 'ContributionsToolLinks':Change tool links above Special:Contributions $id:User identifier $title:User page title &$tools:Array of tool links $specialPage:SpecialPage instance for context and services.Can be either SpecialContributions or DeletedContributionsPage.Extensions should type hint against a generic SpecialPage though. 'ConvertContent':Called by AbstractContent::convert when a conversion to another content model is requested.Handler functions that modify $result should generally return false to disable further attempts at conversion.$content:The Content object to be converted.$toModel:The ID of the content model to convert to.$lossy:boolean indicating whether lossy conversion is allowed.&$result:Output parameter, in case the handler function wants to provide a converted Content object.Note that $result->getContentModel() must return $toModel. 'CustomEditor':When invoking the page editor Return true to allow the normal editor to be used, or false if implementing a custom editor, e.g.for a special namespace, etc.$article:Article being edited $user:User performing the edit 'DatabaseOraclePostInit':Called after initialising an Oracle database $db:the DatabaseOracle object 'DeletedContribsPager::reallyDoQuery':Called before really executing the query for Special:DeletedContributions Similar to ContribsPager::reallyDoQuery &$data:an array of results of all contribs queries $pager:The DeletedContribsPager object hooked into $offset:Index offset, inclusive $limit:Exact query limit $descending:Query direction, false for ascending, true for descending 'DeletedContributionsLineEnding':Called before a DeletedContributions HTML line is finished.Similar to ContributionsLineEnding $page:SpecialPage object for DeletedContributions &$ret:the HTML line $row:the DB row for this line &$classes:the classes to add to the surrounding< li > &$attribs:associative array of other HTML attributes for the< li > element.Currently only data attributes reserved to MediaWiki are allowed(see Sanitizer::isReservedDataAttribute). 'DifferenceEngineAfterLoadNewText':called in DifferenceEngine::loadNewText() after the new revision's content has been loaded into the class member variable $differenceEngine->mNewContent but before returning true from this function.$differenceEngine:DifferenceEngine object 'DifferenceEngineLoadTextAfterNewContentIsLoaded':called in DifferenceEngine::loadText() after the new revision's content has been loaded into the class member variable $differenceEngine->mNewContent but before checking if the variable's value is null.This hook can be used to inject content into said class member variable.$differenceEngine:DifferenceEngine object 'DifferenceEngineMarkPatrolledLink':Allows extensions to change the"mark as patrolled"link which is shown both on the diff header as well as on the bottom of a page, usually wrapped in a span element which has class="patrollink".$differenceEngine:DifferenceEngine object &$markAsPatrolledLink:The"mark as patrolled"link HTML(string) $rcid:Recent change ID(rc_id) for this change(int) 'DifferenceEngineMarkPatrolledRCID':Allows extensions to possibly change the rcid parameter.For example the rcid might be set to zero due to the user being the same as the performer of the change but an extension might still want to show it under certain conditions.&$rcid:rc_id(int) of the change or 0 $differenceEngine:DifferenceEngine object $change:RecentChange object $user:User object representing the current user 'DifferenceEngineNewHeader':Allows extensions to change the $newHeader variable, which contains information about the new revision, such as the revision's author, whether the revision was marked as a minor edit or not, etc.$differenceEngine:DifferenceEngine object &$newHeader:The string containing the various#mw-diff-otitle[1-5] divs, which include things like revision author info, revision comment, RevisionDelete link and more $formattedRevisionTools:Array containing revision tools, some of which may have been injected with the DiffRevisionTools hook $nextlink:String containing the link to the next revision(if any) $status
Definition: hooks.txt:1246
enumFilesInStorage($callback)
Call a callback function for every public file in the repository.
Definition: FileRepo.php:1648
publish($src, $dstRel, $archiveRel, $flags=0, array $options=[])
Copy or move a file either from a storage path, virtual URL, or file system path, into this repositor...
Definition: FileRepo.php:1161
FileBackend $backend
Definition: FileRepo.php:59
fileExistsBatch(array $files)
Checks existence of an array of files.
Definition: FileRepo.php:1365
quickImportBatch(array $triples)
Import a batch of files from the local file system into the repo.
Definition: FileRepo.php:1000
getLocalReference($virtualUrl)
Get a local FS file with a given virtual URL/storage path.
Definition: FileRepo.php:1531
static splitStoragePath($storagePath)
Split a storage path into a backend name, a container name, and a relative file path.
static getDynamicStylesheetQuery()
Get the query to generate a dynamic stylesheet.
Definition: Skin.php:397
quickCleanDir($dir)
Deletes a directory if empty.
Definition: FileRepo.php:980
supportsSha1URLs()
Returns whether or not repo supports having originals SHA-1s in the thumb URLs.
Definition: FileRepo.php:1929
int $deletedHashLevels
The number of directory levels for hash-based division of deleted files.
Definition: FileRepo.php:112
__construct(array $info=null)
Definition: FileRepo.php:139
getZonePath($zone)
Get the storage path corresponding to one of the zones.
Definition: FileRepo.php:363
hasSha1Storage()
Returns whether or not storage is SHA-1 based.
Definition: FileRepo.php:1921
bool $isPrivate
Whether all zones should be private (e.g.
Definition: FileRepo.php:124
see documentation in includes Linker php for Linker::makeImageLink & $time
Definition: hooks.txt:1779
please add to it if you re going to add events to the MediaWiki code where normally authentication against an external auth plugin would be creating a local account $user
Definition: hooks.txt:244
newGood($value=null)
Create a new good result.
Definition: FileRepo.php:1737
findBySha1($hash)
Get an array or iterator of file objects for files that have a given SHA-1 content hash...
Definition: FileRepo.php:570
getName()
Get the name of this repository, as specified by $info['name]' to the constructor.
Definition: FileRepo.php:709
streamFileWithStatus($virtualUrl, $headers=[], $optHeaders=[])
Attempt to stream a file with the given virtual URL/storage path.
Definition: FileRepo.php:1601
publishBatch(array $ntuples, $flags=0)
Publish a batch of files.
Definition: FileRepo.php:1190