wikimedia /
mediawiki
Duplicate code is one of the most pungent code smells. A rule that is often used is to re-structure code once it is duplicated in three or more places.
Common duplication problems, and corresponding solutions are:
Complex classes like FileRepo often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes. You can also have a look at the cohesion graph to spot any un-connected, or weakly-connected components.
Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.
While breaking up the class, it is a good idea to analyze how other classes use FileRepo, and based on these observations, apply Extract Interface, too.
| 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 | |||
| 45 | /** @var bool Whether to fetch commons image description pages and display |
||
| 46 | * them on the local wiki */ |
||
| 47 | public $fetchDescription; |
||
| 48 | |||
| 49 | /** @var int */ |
||
| 50 | public $descriptionCacheExpiry; |
||
| 51 | |||
| 52 | /** @var bool */ |
||
| 53 | protected $hasSha1Storage = false; |
||
| 54 | |||
| 55 | /** @var bool */ |
||
| 56 | protected $supportsSha1URLs = false; |
||
| 57 | |||
| 58 | /** @var FileBackend */ |
||
| 59 | protected $backend; |
||
| 60 | |||
| 61 | /** @var array Map of zones to config */ |
||
| 62 | protected $zones = []; |
||
| 63 | |||
| 64 | /** @var string URL of thumb.php */ |
||
| 65 | protected $thumbScriptUrl; |
||
| 66 | |||
| 67 | /** @var bool Whether to skip media file transformation on parse and rely |
||
| 68 | * on a 404 handler instead. */ |
||
| 69 | protected $transformVia404; |
||
| 70 | |||
| 71 | /** @var string URL of image description pages, e.g. |
||
| 72 | * https://en.wikipedia.org/wiki/File: |
||
| 73 | */ |
||
| 74 | protected $descBaseUrl; |
||
| 75 | |||
| 76 | /** @var string URL of the MediaWiki installation, equivalent to |
||
| 77 | * $wgScriptPath, e.g. https://en.wikipedia.org/w |
||
| 78 | */ |
||
| 79 | protected $scriptDirUrl; |
||
| 80 | |||
| 81 | /** @var string Script extension of the MediaWiki installation, equivalent |
||
| 82 | * to the old $wgScriptExtension, e.g. .php5 defaults to .php */ |
||
| 83 | protected $scriptExtension; |
||
| 84 | |||
| 85 | /** @var string Equivalent to $wgArticlePath, e.g. https://en.wikipedia.org/wiki/$1 */ |
||
| 86 | protected $articleUrl; |
||
| 87 | |||
| 88 | /** @var bool Equivalent to $wgCapitalLinks (or $wgCapitalLinkOverrides[NS_FILE], |
||
| 89 | * determines whether filenames implicitly start with a capital letter. |
||
| 90 | * The current implementation may give incorrect description page links |
||
| 91 | * when the local $wgCapitalLinks and initialCapital are mismatched. |
||
| 92 | */ |
||
| 93 | protected $initialCapital; |
||
| 94 | |||
| 95 | /** @var string May be 'paranoid' to remove all parameters from error |
||
| 96 | * messages, 'none' to leave the paths in unchanged, or 'simple' to |
||
| 97 | * replace paths with placeholders. Default for LocalRepo is |
||
| 98 | * 'simple'. |
||
| 99 | */ |
||
| 100 | protected $pathDisclosureProtection = 'simple'; |
||
| 101 | |||
| 102 | /** @var bool Public zone URL. */ |
||
| 103 | protected $url; |
||
| 104 | |||
| 105 | /** @var string The base thumbnail URL. Defaults to "<url>/thumb". */ |
||
| 106 | protected $thumbUrl; |
||
| 107 | |||
| 108 | /** @var int The number of directory levels for hash-based division of files */ |
||
| 109 | protected $hashLevels; |
||
| 110 | |||
| 111 | /** @var int The number of directory levels for hash-based division of deleted files */ |
||
| 112 | protected $deletedHashLevels; |
||
| 113 | |||
| 114 | /** @var int File names over this size will use the short form of thumbnail |
||
| 115 | * names. Short thumbnail names only have the width, parameters, and the |
||
| 116 | * extension. |
||
| 117 | */ |
||
| 118 | protected $abbrvThreshold; |
||
| 119 | |||
| 120 | /** @var string The URL of the repo's favicon, if any */ |
||
| 121 | protected $favicon; |
||
| 122 | |||
| 123 | /** @var bool Whether all zones should be private (e.g. private wiki repo) */ |
||
| 124 | protected $isPrivate; |
||
| 125 | |||
| 126 | /** @var array callable Override these in the base class */ |
||
| 127 | protected $fileFactory = [ 'UnregisteredLocalFile', 'newFromTitle' ]; |
||
| 128 | /** @var array callable|bool Override these in the base class */ |
||
| 129 | protected $oldFileFactory = false; |
||
| 130 | /** @var array callable|bool Override these in the base class */ |
||
| 131 | protected $fileFactoryKey = false; |
||
| 132 | /** @var array callable|bool Override these in the base class */ |
||
| 133 | protected $oldFileFactoryKey = false; |
||
| 134 | |||
| 135 | /** |
||
| 136 | * @param array|null $info |
||
| 137 | * @throws MWException |
||
| 138 | */ |
||
| 139 | public function __construct( array $info = null ) { |
||
| 209 | |||
| 210 | /** |
||
| 211 | * Get the file backend instance. Use this function wisely. |
||
| 212 | * |
||
| 213 | * @return FileBackend |
||
| 214 | */ |
||
| 215 | public function getBackend() { |
||
| 218 | |||
| 219 | /** |
||
| 220 | * Get an explanatory message if this repo is read-only. |
||
| 221 | * This checks if an administrator disabled writes to the backend. |
||
| 222 | * |
||
| 223 | * @return string|bool Returns false if the repo is not read-only |
||
| 224 | */ |
||
| 225 | public function getReadOnlyReason() { |
||
| 228 | |||
| 229 | /** |
||
| 230 | * Check if a single zone or list of zones is defined for usage |
||
| 231 | * |
||
| 232 | * @param array $doZones Only do a particular zones |
||
| 233 | * @throws MWException |
||
| 234 | * @return Status |
||
| 235 | */ |
||
| 236 | protected function initZones( $doZones = [] ) { |
||
| 247 | |||
| 248 | /** |
||
| 249 | * Determine if a string is an mwrepo:// URL |
||
| 250 | * |
||
| 251 | * @param string $url |
||
| 252 | * @return bool |
||
| 253 | */ |
||
| 254 | public static function isVirtualUrl( $url ) { |
||
| 257 | |||
| 258 | /** |
||
| 259 | * Get a URL referring to this repository, with the private mwrepo protocol. |
||
| 260 | * The suffix, if supplied, is considered to be unencoded, and will be |
||
| 261 | * URL-encoded before being returned. |
||
| 262 | * |
||
| 263 | * @param string|bool $suffix |
||
| 264 | * @return string |
||
| 265 | */ |
||
| 266 | public function getVirtualUrl( $suffix = false ) { |
||
| 274 | |||
| 275 | /** |
||
| 276 | * Get the URL corresponding to one of the four basic zones |
||
| 277 | * |
||
| 278 | * @param string $zone One of: public, deleted, temp, thumb |
||
| 279 | * @param string|null $ext Optional file extension |
||
| 280 | * @return string|bool |
||
| 281 | */ |
||
| 282 | public function getZoneUrl( $zone, $ext = null ) { |
||
| 307 | |||
| 308 | /** |
||
| 309 | * @return bool Whether non-ASCII path characters are allowed |
||
| 310 | */ |
||
| 311 | public function backendSupportsUnicodePaths() { |
||
| 314 | |||
| 315 | /** |
||
| 316 | * Get the backend storage path corresponding to a virtual URL. |
||
| 317 | * Use this function wisely. |
||
| 318 | * |
||
| 319 | * @param string $url |
||
| 320 | * @throws MWException |
||
| 321 | * @return string |
||
| 322 | */ |
||
| 323 | public function resolveVirtualUrl( $url ) { |
||
| 342 | |||
| 343 | /** |
||
| 344 | * The the storage container and base path of a zone |
||
| 345 | * |
||
| 346 | * @param string $zone |
||
| 347 | * @return array (container, base path) or (null, null) |
||
| 348 | */ |
||
| 349 | protected function getZoneLocation( $zone ) { |
||
| 356 | |||
| 357 | /** |
||
| 358 | * Get the storage path corresponding to one of the zones |
||
| 359 | * |
||
| 360 | * @param string $zone |
||
| 361 | * @return string|null Returns null if the zone is not defined |
||
| 362 | */ |
||
| 363 | public function getZonePath( $zone ) { |
||
| 375 | |||
| 376 | /** |
||
| 377 | * Create a new File object from the local repository |
||
| 378 | * |
||
| 379 | * @param Title|string $title Title object or string |
||
| 380 | * @param bool|string $time Time at which the image was uploaded. If this |
||
| 381 | * is specified, the returned object will be an instance of the |
||
| 382 | * repository's old file class instead of a current file. Repositories |
||
| 383 | * not supporting version control should return false if this parameter |
||
| 384 | * is set. |
||
| 385 | * @return File|null A File, or null if passed an invalid Title |
||
| 386 | */ |
||
| 387 | public function newFile( $title, $time = false ) { |
||
| 402 | |||
| 403 | /** |
||
| 404 | * Find an instance of the named file created at the specified time |
||
| 405 | * Returns false if the file does not exist. Repositories not supporting |
||
| 406 | * version control should return false if the time is specified. |
||
| 407 | * |
||
| 408 | * @param Title|string $title Title object or string |
||
| 409 | * @param array $options Associative array of options: |
||
| 410 | * time: requested time for a specific file version, or false for the |
||
| 411 | * current version. An image object will be returned which was |
||
| 412 | * created at the specified time (which may be archived or current). |
||
| 413 | * ignoreRedirect: If true, do not follow file redirects |
||
| 414 | * private: If true, return restricted (deleted) files if the current |
||
| 415 | * user is allowed to view them. Otherwise, such files will not |
||
| 416 | * be found. If a User object, use that user instead of the current. |
||
| 417 | * latest: If true, load from the latest available data into File objects |
||
| 418 | * @return File|bool False on failure |
||
| 419 | */ |
||
| 420 | public function findFile( $title, $options = [] ) { |
||
| 478 | |||
| 479 | /** |
||
| 480 | * Find many files at once. |
||
| 481 | * |
||
| 482 | * @param array $items An array of titles, or an array of findFile() options with |
||
| 483 | * the "title" option giving the title. Example: |
||
| 484 | * |
||
| 485 | * $findItem = array( 'title' => $title, 'private' => true ); |
||
| 486 | * $findBatch = array( $findItem ); |
||
| 487 | * $repo->findFiles( $findBatch ); |
||
| 488 | * |
||
| 489 | * No title should appear in $items twice, as the result use titles as keys |
||
| 490 | * @param int $flags Supports: |
||
| 491 | * - FileRepo::NAME_AND_TIME_ONLY : return a (search title => (title,timestamp)) map. |
||
| 492 | * The search title uses the input titles; the other is the final post-redirect title. |
||
| 493 | * All titles are returned as string DB keys and the inner array is associative. |
||
| 494 | * @return array Map of (file name => File objects) for matches |
||
| 495 | */ |
||
| 496 | public function findFiles( array $items, $flags = 0 ) { |
||
| 523 | |||
| 524 | /** |
||
| 525 | * Find an instance of the file with this key, created at the specified time |
||
| 526 | * Returns false if the file does not exist. Repositories not supporting |
||
| 527 | * version control should return false if the time is specified. |
||
| 528 | * |
||
| 529 | * @param string $sha1 Base 36 SHA-1 hash |
||
| 530 | * @param array $options Option array, same as findFile(). |
||
| 531 | * @return File|bool False on failure |
||
| 532 | */ |
||
| 533 | public function findFileFromKey( $sha1, $options = [] ) { |
||
| 562 | |||
| 563 | /** |
||
| 564 | * Get an array or iterator of file objects for files that have a given |
||
| 565 | * SHA-1 content hash. |
||
| 566 | * |
||
| 567 | * STUB |
||
| 568 | * @param string $hash SHA-1 hash |
||
| 569 | * @return File[] |
||
| 570 | */ |
||
| 571 | public function findBySha1( $hash ) { |
||
| 574 | |||
| 575 | /** |
||
| 576 | * Get an array of arrays or iterators of file objects for files that |
||
| 577 | * have the given SHA-1 content hashes. |
||
| 578 | * |
||
| 579 | * @param array $hashes An array of hashes |
||
| 580 | * @return array An Array of arrays or iterators of file objects and the hash as key |
||
| 581 | */ |
||
| 582 | public function findBySha1s( array $hashes ) { |
||
| 593 | |||
| 594 | /** |
||
| 595 | * Return an array of files where the name starts with $prefix. |
||
| 596 | * |
||
| 597 | * STUB |
||
| 598 | * @param string $prefix The prefix to search for |
||
| 599 | * @param int $limit The maximum amount of files to return |
||
| 600 | * @return array |
||
| 601 | */ |
||
| 602 | public function findFilesByPrefix( $prefix, $limit ) { |
||
| 605 | |||
| 606 | /** |
||
| 607 | * Get the URL of thumb.php |
||
| 608 | * |
||
| 609 | * @return string |
||
| 610 | */ |
||
| 611 | public function getThumbScriptUrl() { |
||
| 614 | |||
| 615 | /** |
||
| 616 | * Returns true if the repository can transform files via a 404 handler |
||
| 617 | * |
||
| 618 | * @return bool |
||
| 619 | */ |
||
| 620 | public function canTransformVia404() { |
||
| 623 | |||
| 624 | /** |
||
| 625 | * Get the name of a file from its title object |
||
| 626 | * |
||
| 627 | * @param Title $title |
||
| 628 | * @return string |
||
| 629 | */ |
||
| 630 | public function getNameFromTitle( Title $title ) { |
||
| 643 | |||
| 644 | /** |
||
| 645 | * Get the public zone root storage directory of the repository |
||
| 646 | * |
||
| 647 | * @return string |
||
| 648 | */ |
||
| 649 | public function getRootDirectory() { |
||
| 652 | |||
| 653 | /** |
||
| 654 | * Get a relative path including trailing slash, e.g. f/fa/ |
||
| 655 | * If the repo is not hashed, returns an empty string |
||
| 656 | * |
||
| 657 | * @param string $name Name of file |
||
| 658 | * @return string |
||
| 659 | */ |
||
| 660 | public function getHashPath( $name ) { |
||
| 663 | |||
| 664 | /** |
||
| 665 | * Get a relative path including trailing slash, e.g. f/fa/ |
||
| 666 | * If the repo is not hashed, returns an empty string |
||
| 667 | * |
||
| 668 | * @param string $suffix Basename of file from FileRepo::storeTemp() |
||
| 669 | * @return string |
||
| 670 | */ |
||
| 671 | public function getTempHashPath( $suffix ) { |
||
| 676 | |||
| 677 | /** |
||
| 678 | * @param string $name |
||
| 679 | * @param int $levels |
||
| 680 | * @return string |
||
| 681 | */ |
||
| 682 | View Code Duplication | protected static function getHashPathForLevel( $name, $levels ) { |
|
| 695 | |||
| 696 | /** |
||
| 697 | * Get the number of hash directory levels |
||
| 698 | * |
||
| 699 | * @return int |
||
| 700 | */ |
||
| 701 | public function getHashLevels() { |
||
| 704 | |||
| 705 | /** |
||
| 706 | * Get the name of this repository, as specified by $info['name]' to the constructor |
||
| 707 | * |
||
| 708 | * @return string |
||
| 709 | */ |
||
| 710 | public function getName() { |
||
| 713 | |||
| 714 | /** |
||
| 715 | * Make an url to this repo |
||
| 716 | * |
||
| 717 | * @param string $query Query string to append |
||
| 718 | * @param string $entry Entry point; defaults to index |
||
| 719 | * @return string|bool False on failure |
||
| 720 | */ |
||
| 721 | public function makeUrl( $query = '', $entry = 'index' ) { |
||
| 730 | |||
| 731 | /** |
||
| 732 | * Get the URL of an image description page. May return false if it is |
||
| 733 | * unknown or not applicable. In general this should only be called by the |
||
| 734 | * File class, since it may return invalid results for certain kinds of |
||
| 735 | * repositories. Use File::getDescriptionUrl() in user code. |
||
| 736 | * |
||
| 737 | * In particular, it uses the article paths as specified to the repository |
||
| 738 | * constructor, whereas local repositories use the local Title functions. |
||
| 739 | * |
||
| 740 | * @param string $name |
||
| 741 | * @return string |
||
| 742 | */ |
||
| 743 | public function getDescriptionUrl( $name ) { |
||
| 766 | |||
| 767 | /** |
||
| 768 | * Get the URL of the content-only fragment of the description page. For |
||
| 769 | * MediaWiki this means action=render. This should only be called by the |
||
| 770 | * repository's file class, since it may return invalid results. User code |
||
| 771 | * should use File::getDescriptionText(). |
||
| 772 | * |
||
| 773 | * @param string $name Name of image to fetch |
||
| 774 | * @param string $lang Language to fetch it in, if any. |
||
| 775 | * @return string |
||
| 776 | */ |
||
| 777 | public function getDescriptionRenderUrl( $name, $lang = null ) { |
||
| 796 | |||
| 797 | /** |
||
| 798 | * Get the URL of the stylesheet to apply to description pages |
||
| 799 | * |
||
| 800 | * @return string|bool False on failure |
||
| 801 | */ |
||
| 802 | public function getDescriptionStylesheetUrl() { |
||
| 810 | |||
| 811 | /** |
||
| 812 | * Store a file to a given destination. |
||
| 813 | * |
||
| 814 | * @param string $srcPath Source file system path, storage path, or virtual URL |
||
| 815 | * @param string $dstZone Destination zone |
||
| 816 | * @param string $dstRel Destination relative path |
||
| 817 | * @param int $flags Bitwise combination of the following flags: |
||
| 818 | * self::OVERWRITE Overwrite an existing destination file instead of failing |
||
| 819 | * self::OVERWRITE_SAME Overwrite the file if the destination exists and has the |
||
| 820 | * same contents as the source |
||
| 821 | * self::SKIP_LOCKING Skip any file locking when doing the store |
||
| 822 | * @return FileRepoStatus |
||
| 823 | */ |
||
| 824 | public function store( $srcPath, $dstZone, $dstRel, $flags = 0 ) { |
||
| 834 | |||
| 835 | /** |
||
| 836 | * Store a batch of files |
||
| 837 | * |
||
| 838 | * @param array $triplets (src, dest zone, dest rel) triplets as per store() |
||
| 839 | * @param int $flags Bitwise combination of the following flags: |
||
| 840 | * self::OVERWRITE Overwrite an existing destination file instead of failing |
||
| 841 | * self::OVERWRITE_SAME Overwrite the file if the destination exists and has the |
||
| 842 | * same contents as the source |
||
| 843 | * self::SKIP_LOCKING Skip any file locking when doing the store |
||
| 844 | * @throws MWException |
||
| 845 | * @return FileRepoStatus |
||
| 846 | */ |
||
| 847 | public function storeBatch( array $triplets, $flags = 0 ) { |
||
| 907 | |||
| 908 | /** |
||
| 909 | * Deletes a batch of files. |
||
| 910 | * Each file can be a (zone, rel) pair, virtual url, storage path. |
||
| 911 | * It will try to delete each file, but ignores any errors that may occur. |
||
| 912 | * |
||
| 913 | * @param array $files List of files to delete |
||
| 914 | * @param int $flags Bitwise combination of the following flags: |
||
| 915 | * self::SKIP_LOCKING Skip any file locking when doing the deletions |
||
| 916 | * @return FileRepoStatus |
||
| 917 | */ |
||
| 918 | public function cleanupBatch( array $files, $flags = 0 ) { |
||
| 944 | |||
| 945 | /** |
||
| 946 | * Import a file from the local file system into the repo. |
||
| 947 | * This does no locking nor journaling and overrides existing files. |
||
| 948 | * This function can be used to write to otherwise read-only foreign repos. |
||
| 949 | * This is intended for copying generated thumbnails into the repo. |
||
| 950 | * |
||
| 951 | * @param string|FSFile $src Source file system path, storage path, or virtual URL |
||
| 952 | * @param string $dst Virtual URL or storage path |
||
| 953 | * @param array|string|null $options An array consisting of a key named headers |
||
| 954 | * listing extra headers. If a string, taken as content-disposition header. |
||
| 955 | * (Support for array of options new in 1.23) |
||
| 956 | * @return FileRepoStatus |
||
| 957 | */ |
||
| 958 | final public function quickImport( $src, $dst, $options = null ) { |
||
| 961 | |||
| 962 | /** |
||
| 963 | * Purge a file from the repo. This does no locking nor journaling. |
||
| 964 | * This function can be used to write to otherwise read-only foreign repos. |
||
| 965 | * This is intended for purging thumbnails. |
||
| 966 | * |
||
| 967 | * @param string $path Virtual URL or storage path |
||
| 968 | * @return FileRepoStatus |
||
| 969 | */ |
||
| 970 | final public function quickPurge( $path ) { |
||
| 973 | |||
| 974 | /** |
||
| 975 | * Deletes a directory if empty. |
||
| 976 | * This function can be used to write to otherwise read-only foreign repos. |
||
| 977 | * |
||
| 978 | * @param string $dir Virtual URL (or storage path) of directory to clean |
||
| 979 | * @return Status |
||
| 980 | */ |
||
| 981 | View Code Duplication | public function quickCleanDir( $dir ) { |
|
| 988 | |||
| 989 | /** |
||
| 990 | * Import a batch of files from the local file system into the repo. |
||
| 991 | * This does no locking nor journaling and overrides existing files. |
||
| 992 | * This function can be used to write to otherwise read-only foreign repos. |
||
| 993 | * This is intended for copying generated thumbnails into the repo. |
||
| 994 | * |
||
| 995 | * All path parameters may be a file system path, storage path, or virtual URL. |
||
| 996 | * When "headers" are given they are used as HTTP headers if supported. |
||
| 997 | * |
||
| 998 | * @param array $triples List of (source path or FSFile, destination path, disposition) |
||
| 999 | * @return FileRepoStatus |
||
| 1000 | */ |
||
| 1001 | public function quickImportBatch( array $triples ) { |
||
| 1037 | |||
| 1038 | /** |
||
| 1039 | * Purge a batch of files from the repo. |
||
| 1040 | * This function can be used to write to otherwise read-only foreign repos. |
||
| 1041 | * This does no locking nor journaling and is intended for purging thumbnails. |
||
| 1042 | * |
||
| 1043 | * @param array $paths List of virtual URLs or storage paths |
||
| 1044 | * @return FileRepoStatus |
||
| 1045 | */ |
||
| 1046 | public function quickPurgeBatch( array $paths ) { |
||
| 1060 | |||
| 1061 | /** |
||
| 1062 | * Pick a random name in the temp zone and store a file to it. |
||
| 1063 | * Returns a FileRepoStatus object with the file Virtual URL in the value, |
||
| 1064 | * file can later be disposed using FileRepo::freeTemp(). |
||
| 1065 | * |
||
| 1066 | * @param string $originalName The base name of the file as specified |
||
| 1067 | * by the user. The file extension will be maintained. |
||
| 1068 | * @param string $srcPath The current location of the file. |
||
| 1069 | * @return FileRepoStatus Object with the URL in the value. |
||
| 1070 | */ |
||
| 1071 | public function storeTemp( $originalName, $srcPath ) { |
||
| 1084 | |||
| 1085 | /** |
||
| 1086 | * Remove a temporary file or mark it for garbage collection |
||
| 1087 | * |
||
| 1088 | * @param string $virtualUrl The virtual URL returned by FileRepo::storeTemp() |
||
| 1089 | * @return bool True on success, false on failure |
||
| 1090 | */ |
||
| 1091 | public function freeTemp( $virtualUrl ) { |
||
| 1103 | |||
| 1104 | /** |
||
| 1105 | * Concatenate a list of temporary files into a target file location. |
||
| 1106 | * |
||
| 1107 | * @param array $srcPaths Ordered list of source virtual URLs/storage paths |
||
| 1108 | * @param string $dstPath Target file system path |
||
| 1109 | * @param int $flags Bitwise combination of the following flags: |
||
| 1110 | * self::DELETE_SOURCE Delete the source files on success |
||
| 1111 | * @return FileRepoStatus |
||
| 1112 | */ |
||
| 1113 | public function concatenate( array $srcPaths, $dstPath, $flags = 0 ) { |
||
| 1142 | |||
| 1143 | /** |
||
| 1144 | * Copy or move a file either from a storage path, virtual URL, |
||
| 1145 | * or file system path, into this repository at the specified destination location. |
||
| 1146 | * |
||
| 1147 | * Returns a FileRepoStatus object. On success, the value contains "new" or |
||
| 1148 | * "archived", to indicate whether the file was new with that name. |
||
| 1149 | * |
||
| 1150 | * Options to $options include: |
||
| 1151 | * - headers : name/value map of HTTP headers to use in response to GET/HEAD requests |
||
| 1152 | * |
||
| 1153 | * @param string|FSFile $src The source file system path, storage path, or URL |
||
| 1154 | * @param string $dstRel The destination relative path |
||
| 1155 | * @param string $archiveRel The relative path where the existing file is to |
||
| 1156 | * be archived, if there is one. Relative to the public zone root. |
||
| 1157 | * @param int $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate |
||
| 1158 | * that the source file should be deleted if possible |
||
| 1159 | * @param array $options Optional additional parameters |
||
| 1160 | * @return FileRepoStatus |
||
| 1161 | */ |
||
| 1162 | public function publish( |
||
| 1180 | |||
| 1181 | /** |
||
| 1182 | * Publish a batch of files |
||
| 1183 | * |
||
| 1184 | * @param array $ntuples (source, dest, archive) triplets or |
||
| 1185 | * (source, dest, archive, options) 4-tuples as per publish(). |
||
| 1186 | * @param int $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate |
||
| 1187 | * that the source files should be deleted if possible |
||
| 1188 | * @throws MWException |
||
| 1189 | * @return FileRepoStatus |
||
| 1190 | */ |
||
| 1191 | public function publishBatch( array $ntuples, $flags = 0 ) { |
||
| 1304 | |||
| 1305 | /** |
||
| 1306 | * Creates a directory with the appropriate zone permissions. |
||
| 1307 | * Callers are responsible for doing read-only and "writable repo" checks. |
||
| 1308 | * |
||
| 1309 | * @param string $dir Virtual URL (or storage path) of directory to clean |
||
| 1310 | * @return Status |
||
| 1311 | */ |
||
| 1312 | protected function initDirectory( $dir ) { |
||
| 1328 | |||
| 1329 | /** |
||
| 1330 | * Deletes a directory if empty. |
||
| 1331 | * |
||
| 1332 | * @param string $dir Virtual URL (or storage path) of directory to clean |
||
| 1333 | * @return Status |
||
| 1334 | */ |
||
| 1335 | View Code Duplication | public function cleanDir( $dir ) { |
|
| 1344 | |||
| 1345 | /** |
||
| 1346 | * Checks existence of a a file |
||
| 1347 | * |
||
| 1348 | * @param string $file Virtual URL (or storage path) of file to check |
||
| 1349 | * @return bool |
||
| 1350 | */ |
||
| 1351 | public function fileExists( $file ) { |
||
| 1356 | |||
| 1357 | /** |
||
| 1358 | * Checks existence of an array of files. |
||
| 1359 | * |
||
| 1360 | * @param array $files Virtual URLs (or storage paths) of files to check |
||
| 1361 | * @return array Map of files and existence flags, or false |
||
| 1362 | */ |
||
| 1363 | public function fileExistsBatch( array $files ) { |
||
| 1375 | |||
| 1376 | /** |
||
| 1377 | * Move a file to the deletion archive. |
||
| 1378 | * If no valid deletion archive exists, this may either delete the file |
||
| 1379 | * or throw an exception, depending on the preference of the repository |
||
| 1380 | * |
||
| 1381 | * @param mixed $srcRel Relative path for the file to be deleted |
||
| 1382 | * @param mixed $archiveRel Relative path for the archive location. |
||
| 1383 | * Relative to a private archive directory. |
||
| 1384 | * @return FileRepoStatus |
||
| 1385 | */ |
||
| 1386 | public function delete( $srcRel, $archiveRel ) { |
||
| 1391 | |||
| 1392 | /** |
||
| 1393 | * Move a group of files to the deletion archive. |
||
| 1394 | * |
||
| 1395 | * If no valid deletion archive is configured, this may either delete the |
||
| 1396 | * file or throw an exception, depending on the preference of the repository. |
||
| 1397 | * |
||
| 1398 | * The overwrite policy is determined by the repository -- currently LocalRepo |
||
| 1399 | * assumes a naming scheme in the deleted zone based on content hash, as |
||
| 1400 | * opposed to the public zone which is assumed to be unique. |
||
| 1401 | * |
||
| 1402 | * @param array $sourceDestPairs Array of source/destination pairs. Each element |
||
| 1403 | * is a two-element array containing the source file path relative to the |
||
| 1404 | * public root in the first element, and the archive file path relative |
||
| 1405 | * to the deleted zone root in the second element. |
||
| 1406 | * @throws MWException |
||
| 1407 | * @return FileRepoStatus |
||
| 1408 | */ |
||
| 1409 | public function deleteBatch( array $sourceDestPairs ) { |
||
| 1461 | |||
| 1462 | /** |
||
| 1463 | * Delete files in the deleted directory if they are not referenced in the filearchive table |
||
| 1464 | * |
||
| 1465 | * STUB |
||
| 1466 | * @param array $storageKeys |
||
| 1467 | */ |
||
| 1468 | public function cleanupDeletedBatch( array $storageKeys ) { |
||
| 1471 | |||
| 1472 | /** |
||
| 1473 | * Get a relative path for a deletion archive key, |
||
| 1474 | * e.g. s/z/a/ for sza251lrxrc1jad41h5mgilp8nysje52.jpg |
||
| 1475 | * |
||
| 1476 | * @param string $key |
||
| 1477 | * @throws MWException |
||
| 1478 | * @return string |
||
| 1479 | */ |
||
| 1480 | public function getDeletedHashPath( $key ) { |
||
| 1491 | |||
| 1492 | /** |
||
| 1493 | * If a path is a virtual URL, resolve it to a storage path. |
||
| 1494 | * Otherwise, just return the path as it is. |
||
| 1495 | * |
||
| 1496 | * @param string $path |
||
| 1497 | * @return string |
||
| 1498 | * @throws MWException |
||
| 1499 | */ |
||
| 1500 | protected function resolveToStoragePath( $path ) { |
||
| 1507 | |||
| 1508 | /** |
||
| 1509 | * Get a local FS copy of a file with a given virtual URL/storage path. |
||
| 1510 | * Temporary files may be purged when the file object falls out of scope. |
||
| 1511 | * |
||
| 1512 | * @param string $virtualUrl |
||
| 1513 | * @return TempFSFile|null Returns null on failure |
||
| 1514 | */ |
||
| 1515 | public function getLocalCopy( $virtualUrl ) { |
||
| 1520 | |||
| 1521 | /** |
||
| 1522 | * Get a local FS file with a given virtual URL/storage path. |
||
| 1523 | * The file is either an original or a copy. It should not be changed. |
||
| 1524 | * Temporary files may be purged when the file object falls out of scope. |
||
| 1525 | * |
||
| 1526 | * @param string $virtualUrl |
||
| 1527 | * @return FSFile|null Returns null on failure. |
||
| 1528 | */ |
||
| 1529 | public function getLocalReference( $virtualUrl ) { |
||
| 1534 | |||
| 1535 | /** |
||
| 1536 | * Get properties of a file with a given virtual URL/storage path. |
||
| 1537 | * Properties should ultimately be obtained via FSFile::getProps(). |
||
| 1538 | * |
||
| 1539 | * @param string $virtualUrl |
||
| 1540 | * @return array |
||
| 1541 | */ |
||
| 1542 | public function getFileProps( $virtualUrl ) { |
||
| 1547 | |||
| 1548 | /** |
||
| 1549 | * Get the timestamp of a file with a given virtual URL/storage path |
||
| 1550 | * |
||
| 1551 | * @param string $virtualUrl |
||
| 1552 | * @return string|bool False on failure |
||
| 1553 | */ |
||
| 1554 | public function getFileTimestamp( $virtualUrl ) { |
||
| 1559 | |||
| 1560 | /** |
||
| 1561 | * Get the size of a file with a given virtual URL/storage path |
||
| 1562 | * |
||
| 1563 | * @param string $virtualUrl |
||
| 1564 | * @return int|bool False on failure |
||
| 1565 | */ |
||
| 1566 | public function getFileSize( $virtualUrl ) { |
||
| 1571 | |||
| 1572 | /** |
||
| 1573 | * Get the sha1 (base 36) of a file with a given virtual URL/storage path |
||
| 1574 | * |
||
| 1575 | * @param string $virtualUrl |
||
| 1576 | * @return string|bool |
||
| 1577 | */ |
||
| 1578 | public function getFileSha1( $virtualUrl ) { |
||
| 1583 | |||
| 1584 | /** |
||
| 1585 | * Attempt to stream a file with the given virtual URL/storage path |
||
| 1586 | * |
||
| 1587 | * @param string $virtualUrl |
||
| 1588 | * @param array $headers Additional HTTP headers to send on success |
||
| 1589 | * @return Status |
||
| 1590 | * @since 1.27 |
||
| 1591 | */ |
||
| 1592 | public function streamFileWithStatus( $virtualUrl, $headers = [] ) { |
||
| 1598 | |||
| 1599 | /** |
||
| 1600 | * Attempt to stream a file with the given virtual URL/storage path |
||
| 1601 | * |
||
| 1602 | * @deprecated since 1.26, use streamFileWithStatus |
||
| 1603 | * @param string $virtualUrl |
||
| 1604 | * @param array $headers Additional HTTP headers to send on success |
||
| 1605 | * @return bool Success |
||
| 1606 | */ |
||
| 1607 | public function streamFile( $virtualUrl, $headers = [] ) { |
||
| 1610 | |||
| 1611 | /** |
||
| 1612 | * Call a callback function for every public regular file in the repository. |
||
| 1613 | * This only acts on the current version of files, not any old versions. |
||
| 1614 | * May use either the database or the filesystem. |
||
| 1615 | * |
||
| 1616 | * @param callable $callback |
||
| 1617 | * @return void |
||
| 1618 | */ |
||
| 1619 | public function enumFiles( $callback ) { |
||
| 1622 | |||
| 1623 | /** |
||
| 1624 | * Call a callback function for every public file in the repository. |
||
| 1625 | * May use either the database or the filesystem. |
||
| 1626 | * |
||
| 1627 | * @param callable $callback |
||
| 1628 | * @return void |
||
| 1629 | */ |
||
| 1630 | protected function enumFilesInStorage( $callback ) { |
||
| 1648 | |||
| 1649 | /** |
||
| 1650 | * Determine if a relative path is valid, i.e. not blank or involving directory traveral |
||
| 1651 | * |
||
| 1652 | * @param string $filename |
||
| 1653 | * @return bool |
||
| 1654 | */ |
||
| 1655 | public function validateFilename( $filename ) { |
||
| 1662 | |||
| 1663 | /** |
||
| 1664 | * Get a callback function to use for cleaning error message parameters |
||
| 1665 | * |
||
| 1666 | * @return array |
||
| 1667 | */ |
||
| 1668 | function getErrorCleanupFunction() { |
||
| 1679 | |||
| 1680 | /** |
||
| 1681 | * Path disclosure protection function |
||
| 1682 | * |
||
| 1683 | * @param string $param |
||
| 1684 | * @return string |
||
| 1685 | */ |
||
| 1686 | function paranoidClean( $param ) { |
||
| 1689 | |||
| 1690 | /** |
||
| 1691 | * Path disclosure protection function |
||
| 1692 | * |
||
| 1693 | * @param string $param |
||
| 1694 | * @return string |
||
| 1695 | */ |
||
| 1696 | function passThrough( $param ) { |
||
| 1699 | |||
| 1700 | /** |
||
| 1701 | * Create a new fatal error |
||
| 1702 | * |
||
| 1703 | * @param string $message |
||
| 1704 | * @return Status |
||
| 1705 | */ |
||
| 1706 | public function newFatal( $message /*, parameters...*/ ) { |
||
| 1712 | |||
| 1713 | /** |
||
| 1714 | * Create a new good result |
||
| 1715 | * |
||
| 1716 | * @param null|string $value |
||
| 1717 | * @return Status |
||
| 1718 | */ |
||
| 1719 | public function newGood( $value = null ) { |
||
| 1725 | |||
| 1726 | /** |
||
| 1727 | * Checks if there is a redirect named as $title. If there is, return the |
||
| 1728 | * title object. If not, return false. |
||
| 1729 | * STUB |
||
| 1730 | * |
||
| 1731 | * @param Title $title Title of image |
||
| 1732 | * @return bool |
||
| 1733 | */ |
||
| 1734 | public function checkRedirect( Title $title ) { |
||
| 1737 | |||
| 1738 | /** |
||
| 1739 | * Invalidates image redirect cache related to that image |
||
| 1740 | * Doesn't do anything for repositories that don't support image redirects. |
||
| 1741 | * |
||
| 1742 | * STUB |
||
| 1743 | * @param Title $title Title of image |
||
| 1744 | */ |
||
| 1745 | public function invalidateImageRedirect( Title $title ) { |
||
| 1747 | |||
| 1748 | /** |
||
| 1749 | * Get the human-readable name of the repo |
||
| 1750 | * |
||
| 1751 | * @return string |
||
| 1752 | */ |
||
| 1753 | public function getDisplayName() { |
||
| 1763 | |||
| 1764 | /** |
||
| 1765 | * Get the portion of the file that contains the origin file name. |
||
| 1766 | * If that name is too long, then the name "thumbnail.<ext>" will be given. |
||
| 1767 | * |
||
| 1768 | * @param string $name |
||
| 1769 | * @return string |
||
| 1770 | */ |
||
| 1771 | public function nameForThumb( $name ) { |
||
| 1779 | |||
| 1780 | /** |
||
| 1781 | * Returns true if this the local file repository. |
||
| 1782 | * |
||
| 1783 | * @return bool |
||
| 1784 | */ |
||
| 1785 | public function isLocal() { |
||
| 1788 | |||
| 1789 | /** |
||
| 1790 | * Get a key on the primary cache for this repository. |
||
| 1791 | * Returns false if the repository's cache is not accessible at this site. |
||
| 1792 | * The parameters are the parts of the key, as for wfMemcKey(). |
||
| 1793 | * |
||
| 1794 | * STUB |
||
| 1795 | * @return bool |
||
| 1796 | */ |
||
| 1797 | public function getSharedCacheKey( /*...*/ ) { |
||
| 1800 | |||
| 1801 | /** |
||
| 1802 | * Get a key for this repo in the local cache domain. These cache keys are |
||
| 1803 | * not shared with remote instances of the repo. |
||
| 1804 | * The parameters are the parts of the key, as for wfMemcKey(). |
||
| 1805 | * |
||
| 1806 | * @return string |
||
| 1807 | */ |
||
| 1808 | public function getLocalCacheKey( /*...*/ ) { |
||
| 1814 | |||
| 1815 | /** |
||
| 1816 | * Get a temporary private FileRepo associated with this repo. |
||
| 1817 | * |
||
| 1818 | * Files will be created in the temp zone of this repo. |
||
| 1819 | * It will have the same backend as this repo. |
||
| 1820 | * |
||
| 1821 | * @return TempFileRepo |
||
| 1822 | */ |
||
| 1823 | public function getTempRepo() { |
||
| 1851 | |||
| 1852 | /** |
||
| 1853 | * Get an UploadStash associated with this repo. |
||
| 1854 | * |
||
| 1855 | * @param User $user |
||
| 1856 | * @return UploadStash |
||
| 1857 | */ |
||
| 1858 | public function getUploadStash( User $user = null ) { |
||
| 1861 | |||
| 1862 | /** |
||
| 1863 | * Throw an exception if this repo is read-only by design. |
||
| 1864 | * This does not and should not check getReadOnlyReason(). |
||
| 1865 | * |
||
| 1866 | * @return void |
||
| 1867 | * @throws MWException |
||
| 1868 | */ |
||
| 1869 | protected function assertWritableRepo() { |
||
| 1871 | |||
| 1872 | /** |
||
| 1873 | * Return information about the repository. |
||
| 1874 | * |
||
| 1875 | * @return array |
||
| 1876 | * @since 1.22 |
||
| 1877 | */ |
||
| 1878 | public function getInfo() { |
||
| 1898 | |||
| 1899 | /** |
||
| 1900 | * Returns whether or not storage is SHA-1 based |
||
| 1901 | * @return bool |
||
| 1902 | */ |
||
| 1903 | public function hasSha1Storage() { |
||
| 1906 | |||
| 1907 | /** |
||
| 1908 | * Returns whether or not repo supports having originals SHA-1s in the thumb URLs |
||
| 1909 | * @return bool |
||
| 1910 | */ |
||
| 1911 | public function supportsSha1URLs() { |
||
| 1914 | } |
||
| 1915 | |||
| 1924 |
Loading history...
In PHP it is possible to write to properties without declaring them. For example, the following is perfectly valid PHP code:
Generally, it is a good practice to explictly declare properties to avoid accidental typos and provide IDE auto-completion: