From 417d4fbbfa8e72fc3d05535eff7d9c783aea4acb Mon Sep 17 00:00:00 2001 From: Siebrand Mazeland Date: Wed, 4 Dec 2013 17:18:05 +0100 Subject: [PATCH] Update documentation for file repo related classes Change-Id: I626d972f92934afc9349e11d3a5550c4044dcb53 --- includes/filerepo/FSRepo.php | 2 +- includes/filerepo/FileRepo.php | 187 +++++++++--------- includes/filerepo/FileRepoStatus.php | 2 +- includes/filerepo/ForeignAPIRepo.php | 56 +++--- includes/filerepo/ForeignDBRepo.php | 18 +- includes/filerepo/ForeignDBViaLBRepo.php | 11 +- includes/filerepo/LocalRepo.php | 27 ++- includes/filerepo/NullRepo.php | 3 +- includes/filerepo/RepoGroup.php | 53 ++--- includes/filerepo/file/ArchivedFile.php | 11 +- includes/filerepo/file/File.php | 174 ++++++++-------- includes/filerepo/file/ForeignAPIFile.php | 23 ++- includes/filerepo/file/ForeignDBFile.php | 37 ++-- includes/filerepo/file/LocalFile.php | 176 +++++++++-------- includes/filerepo/file/OldLocalFile.php | 51 +++-- .../filerepo/file/UnregisteredLocalFile.php | 30 +-- 16 files changed, 439 insertions(+), 422 deletions(-) diff --git a/includes/filerepo/FSRepo.php b/includes/filerepo/FSRepo.php index 046b97c6bb..edf0eec463 100644 --- a/includes/filerepo/FSRepo.php +++ b/includes/filerepo/FSRepo.php @@ -32,7 +32,7 @@ */ class FSRepo extends FileRepo { /** - * @param $info array + * @param array $info * @throws MWException */ function __construct( array $info ) { diff --git a/includes/filerepo/FileRepo.php b/includes/filerepo/FileRepo.php index 47efa705d0..98e785f19d 100644 --- a/includes/filerepo/FileRepo.php +++ b/includes/filerepo/FileRepo.php @@ -119,7 +119,7 @@ class FileRepo { protected $oldFileFactoryKey = false; /** - * @param $info array|null + * @param array|null $info * @throws MWException */ public function __construct( array $info = null ) { @@ -232,7 +232,7 @@ class FileRepo { /** * Determine if a string is an mwrepo:// URL * - * @param $url string + * @param string $url * @return bool */ public static function isVirtualUrl( $url ) { @@ -244,7 +244,7 @@ class FileRepo { * The suffix, if supplied, is considered to be unencoded, and will be * URL-encoded before being returned. * - * @param $suffix string|bool + * @param string|bool $suffix * @return string */ public function getVirtualUrl( $suffix = false ) { @@ -301,7 +301,7 @@ class FileRepo { * same host name as the wiki that is used for viewing thumbnails. * * @param string $zone one of: public, deleted, temp, thumb - * @return String or false + * @return string|bool String or false */ public function getZoneHandlerUrl( $zone ) { if ( isset( $this->zones[$zone]['handlerUrl'] ) @@ -317,7 +317,7 @@ class FileRepo { * Get the backend storage path corresponding to a virtual URL. * Use this function wisely. * - * @param $url string + * @param string $url * @throws MWException * @return string */ @@ -344,8 +344,8 @@ class FileRepo { /** * The the storage container and base path of a zone * - * @param $zone string - * @return Array (container, base path) or (null, null) + * @param string $zone + * @return array (container, base path) or (null, null) */ protected function getZoneLocation( $zone ) { if ( !isset( $this->zones[$zone] ) ) { @@ -358,7 +358,7 @@ class FileRepo { /** * Get the storage path corresponding to one of the zones * - * @param $zone string + * @param string $zone * @return string|null Returns null if the zone is not defined */ public function getZonePath( $zone ) { @@ -377,12 +377,12 @@ class FileRepo { /** * Create a new File object from the local repository * - * @param $title Mixed: Title object or string - * @param $time Mixed: Time at which the image was uploaded. - * If this is specified, the returned object will be an - * instance of the repository's old file class instead of a - * current file. Repositories not supporting version control - * should return false if this parameter is set. + * @param Title|string $title Title object or string + * @param bool|string $time Time at which the image was uploaded. If this + * is specified, the returned object will be an instance of the + * repository's old file class instead of a current file. Repositories + * not supporting version control should return false if this parameter + * is set. * @return File|null A File, or null if passed an invalid Title */ public function newFile( $title, $time = false ) { @@ -406,17 +406,15 @@ class FileRepo { * Returns false if the file does not exist. Repositories not supporting * version control should return false if the time is specified. * - * @param $title Mixed: Title object or string + * @param Title|string $title Title object or string * @param array $options Associative array of options: - * time: requested time for a specific file version, or false for the - * current version. An image object will be returned which was - * created at the specified time (which may be archived or current). - * - * ignoreRedirect: If true, do not follow file redirects - * - * private: If true, return restricted (deleted) files if the current - * user is allowed to view them. Otherwise, such files will not - * be found. + * time: requested time for a specific file version, or false for the + * current version. An image object will be returned which was + * created at the specified time (which may be archived or current). + * ignoreRedirect: If true, do not follow file redirects + * private: If true, return restricted (deleted) files if the current + * user is allowed to view them. Otherwise, such files will not + * be found. * @return File|bool False on failure */ public function findFile( $title, $options = array() ) { @@ -501,7 +499,7 @@ class FileRepo { * Returns false if the file does not exist. Repositories not supporting * version control should return false if the time is specified. * - * @param string $sha1 base 36 SHA-1 hash + * @param string $sha1 Base 36 SHA-1 hash * @param array $options Option array, same as findFile(). * @return File|bool False on failure */ @@ -536,7 +534,7 @@ class FileRepo { * SHA-1 content hash. * * STUB - * @param $hash + * @param string $hash SHA-1 hash * @return array */ public function findBySha1( $hash ) { @@ -605,8 +603,8 @@ class FileRepo { /** * Get the name of a file from its title object * - * @param $title Title - * @return String + * @param Title $title + * @return string */ public function getNameFromTitle( Title $title ) { global $wgContLang; @@ -656,8 +654,8 @@ class FileRepo { } /** - * @param $name - * @param $levels + * @param string $name + * @param int $levels * @return string */ protected static function getHashPathForLevel( $name, $levels ) { @@ -677,7 +675,7 @@ class FileRepo { /** * Get the number of hash directory levels * - * @return integer + * @return int */ public function getHashLevels() { return $this->hashLevels; @@ -695,7 +693,7 @@ class FileRepo { /** * Make an url to this repo * - * @param $query mixed Query string to append + * @param string $query Query string to append * @param string $entry Entry point; defaults to index * @return string|bool False on failure */ @@ -718,7 +716,7 @@ class FileRepo { * In particular, it uses the article paths as specified to the repository * constructor, whereas local repositories use the local Title functions. * - * @param $name string + * @param string $name * @return string */ public function getDescriptionUrl( $name ) { @@ -753,8 +751,8 @@ class FileRepo { * repository's file class, since it may return invalid results. User code * should use File::getDescriptionText(). * - * @param string $name name of image to fetch - * @param string $lang language to fetch it in, if any. + * @param string $name Name of image to fetch + * @param string $lang Language to fetch it in, if any. * @return string */ public function getDescriptionRenderUrl( $name, $lang = null ) { @@ -794,15 +792,15 @@ class FileRepo { /** * Store a file to a given destination. * - * @param string $srcPath source file system path, storage path, or virtual URL - * @param string $dstZone destination zone - * @param string $dstRel destination relative path - * @param $flags Integer: bitwise combination of the following flags: - * self::DELETE_SOURCE Delete the source file after upload - * self::OVERWRITE Overwrite an existing destination file instead of failing - * self::OVERWRITE_SAME Overwrite the file if the destination exists and has the - * same contents as the source - * self::SKIP_LOCKING Skip any file locking when doing the store + * @param string $srcPath Source file system path, storage path, or virtual URL + * @param string $dstZone Destination zone + * @param string $dstRel Destination relative path + * @param int $flags Bitwise combination of the following flags: + * self::DELETE_SOURCE Delete the source file after upload + * self::OVERWRITE Overwrite an existing destination file instead of failing + * self::OVERWRITE_SAME Overwrite the file if the destination exists and has the + * same contents as the source + * self::SKIP_LOCKING Skip any file locking when doing the store * @return FileRepoStatus */ public function store( $srcPath, $dstZone, $dstRel, $flags = 0 ) { @@ -820,12 +818,12 @@ class FileRepo { * Store a batch of files * * @param array $triplets (src, dest zone, dest rel) triplets as per store() - * @param $flags Integer: bitwise combination of the following flags: - * self::DELETE_SOURCE Delete the source file after upload - * self::OVERWRITE Overwrite an existing destination file instead of failing - * self::OVERWRITE_SAME Overwrite the file if the destination exists and has the - * same contents as the source - * self::SKIP_LOCKING Skip any file locking when doing the store + * @param int $flags Bitwise combination of the following flags: + * self::DELETE_SOURCE Delete the source file after upload + * self::OVERWRITE Overwrite an existing destination file instead of failing + * self::OVERWRITE_SAME Overwrite the file if the destination exists and has the + * same contents as the source + * self::SKIP_LOCKING Skip any file locking when doing the store * @throws MWException * @return FileRepoStatus */ @@ -902,8 +900,8 @@ class FileRepo { * It will try to delete each file, but ignores any errors that may occur. * * @param array $files List of files to delete - * @param $flags Integer: bitwise combination of the following flags: - * self::SKIP_LOCKING Skip any file locking when doing the deletions + * @param int $flags Bitwise combination of the following flags: + * self::SKIP_LOCKING Skip any file locking when doing the deletions * @return FileRepoStatus */ public function cleanupBatch( array $files, $flags = 0 ) { @@ -1036,9 +1034,9 @@ class FileRepo { * file can later be disposed using FileRepo::freeTemp(). * * @param string $originalName the base name of the file as specified - * by the user. The file extension will be maintained. - * @param string $srcPath the current location of the file. - * @return FileRepoStatus object with the URL in the value. + * by the user. The file extension will be maintained. + * @param string $srcPath The current location of the file. + * @return FileRepoStatus Object with the URL in the value. */ public function storeTemp( $originalName, $srcPath ) { $this->assertWritableRepo(); // fail out if read-only @@ -1057,8 +1055,8 @@ class FileRepo { /** * Remove a temporary file or mark it for garbage collection * - * @param string $virtualUrl the virtual URL returned by FileRepo::storeTemp() - * @return Boolean: true on success, false on failure + * @param string $virtualUrl The virtual URL returned by FileRepo::storeTemp() + * @return bool True on success, false on failure */ public function freeTemp( $virtualUrl ) { $this->assertWritableRepo(); // fail out if read-only @@ -1078,8 +1076,8 @@ class FileRepo { * * @param array $srcPaths Ordered list of source virtual URLs/storage paths * @param string $dstPath Target file system path - * @param $flags Integer: bitwise combination of the following flags: - * self::DELETE_SOURCE Delete the source files + * @param int $flags Bitwise combination of the following flags: + * self::DELETE_SOURCE Delete the source files * @return FileRepoStatus */ public function concatenate( array $srcPaths, $dstPath, $flags = 0 ) { @@ -1122,12 +1120,12 @@ class FileRepo { * Options to $options include: * - headers : name/value map of HTTP headers to use in response to GET/HEAD requests * - * @param string $srcPath the source file system path, storage path, or URL - * @param string $dstRel the destination relative path - * @param string $archiveRel the relative path where the existing file is to - * be archived, if there is one. Relative to the public zone root. - * @param $flags Integer: bitfield, may be FileRepo::DELETE_SOURCE to indicate - * that the source file should be deleted if possible + * @param string $srcPath The source file system path, storage path, or URL + * @param string $dstRel The destination relative path + * @param string $archiveRel The relative path where the existing file is to + * be archived, if there is one. Relative to the public zone root. + * @param int $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate + * that the source file should be deleted if possible * @param array $options Optional additional parameters * @return FileRepoStatus */ @@ -1154,9 +1152,9 @@ class FileRepo { * Publish a batch of files * * @param array $ntuples (source, dest, archive) triplets or - * (source, dest, archive, options) 4-tuples as per publish(). - * @param $flags Integer: bitfield, may be FileRepo::DELETE_SOURCE to indicate - * that the source files should be deleted if possible + * (source, dest, archive, options) 4-tuples as per publish(). + * @param int $flags Bitfield, may be FileRepo::DELETE_SOURCE to indicate + * that the source files should be deleted if possible * @throws MWException * @return FileRepoStatus */ @@ -1342,9 +1340,9 @@ class FileRepo { * If no valid deletion archive exists, this may either delete the file * or throw an exception, depending on the preference of the repository * - * @param $srcRel Mixed: relative path for the file to be deleted - * @param $archiveRel Mixed: relative path for the archive location. - * Relative to a private archive directory. + * @param mixed $srcRel Relative path for the file to be deleted + * @param mixed $archiveRel Relative path for the archive location. + * Relative to a private archive directory. * @return FileRepoStatus object */ public function delete( $srcRel, $archiveRel ) { @@ -1363,10 +1361,10 @@ class FileRepo { * assumes a naming scheme in the deleted zone based on content hash, as * opposed to the public zone which is assumed to be unique. * - * @param array $sourceDestPairs of source/destination pairs. Each element - * is a two-element array containing the source file path relative to the - * public root in the first element, and the archive file path relative - * to the deleted zone root in the second element. + * @param array $sourceDestPairs Array of source/destination pairs. Each element + * is a two-element array containing the source file path relative to the + * public root in the first element, and the archive file path relative + * to the deleted zone root in the second element. * @throws MWException * @return FileRepoStatus */ @@ -1436,7 +1434,7 @@ class FileRepo { * Get a relative path for a deletion archive key, * e.g. s/z/a/ for sza251lrxrc1jad41h5mgilp8nysje52.jpg * - * @param $key string + * @param string $key * @throws MWException * @return string */ @@ -1456,7 +1454,7 @@ class FileRepo { * If a path is a virtual URL, resolve it to a storage path. * Otherwise, just return the path as it is. * - * @param $path string + * @param string $path * @return string * @throws MWException */ @@ -1472,7 +1470,7 @@ class FileRepo { * Get a local FS copy of a file with a given virtual URL/storage path. * Temporary files may be purged when the file object falls out of scope. * - * @param $virtualUrl string + * @param string $virtualUrl * @return TempFSFile|null Returns null on failure */ public function getLocalCopy( $virtualUrl ) { @@ -1486,7 +1484,7 @@ class FileRepo { * The file is either an original or a copy. It should not be changed. * Temporary files may be purged when the file object falls out of scope. * - * @param $virtualUrl string + * @param string $virtualUrl * @return FSFile|null Returns null on failure. */ public function getLocalReference( $virtualUrl ) { @@ -1499,7 +1497,7 @@ class FileRepo { * Get properties of a file with a given virtual URL/storage path. * Properties should ultimately be obtained via FSFile::getProps(). * - * @param $virtualUrl string + * @param string $virtualUrl * @return Array */ public function getFileProps( $virtualUrl ) { @@ -1511,7 +1509,7 @@ class FileRepo { /** * Get the timestamp of a file with a given virtual URL/storage path * - * @param $virtualUrl string + * @param string $virtualUrl * @return string|bool False on failure */ public function getFileTimestamp( $virtualUrl ) { @@ -1523,7 +1521,7 @@ class FileRepo { /** * Get the size of a file with a given virtual URL/storage path * - * @param $virtualUrl string + * @param string $virtualUrl * @return integer|bool False on failure */ public function getFileSize( $virtualUrl ) { @@ -1535,7 +1533,7 @@ class FileRepo { /** * Get the sha1 (base 36) of a file with a given virtual URL/storage path * - * @param $virtualUrl string + * @param string $virtualUrl * @return string|bool */ public function getFileSha1( $virtualUrl ) { @@ -1547,7 +1545,7 @@ class FileRepo { /** * Attempt to stream a file with the given virtual URL/storage path * - * @param $virtualUrl string + * @param string $virtualUrl * @param array $headers Additional HTTP headers to send on success * @return bool Success */ @@ -1563,7 +1561,7 @@ class FileRepo { * This only acts on the current version of files, not any old versions. * May use either the database or the filesystem. * - * @param $callback Array|string + * @param array|string $callback * @return void */ public function enumFiles( $callback ) { @@ -1574,7 +1572,7 @@ class FileRepo { * Call a callback function for every public file in the repository. * May use either the database or the filesystem. * - * @param $callback Array|string + * @param array|string $callback * @return void */ protected function enumFilesInStorage( $callback ) { @@ -1613,7 +1611,7 @@ class FileRepo { /** * Get a callback function to use for cleaning error message parameters * - * @return Array + * @return array */ function getErrorCleanupFunction() { switch ( $this->pathDisclosureProtection ) { @@ -1630,7 +1628,7 @@ class FileRepo { /** * Path disclosure protection function * - * @param $param string + * @param string $param * @return string */ function paranoidClean( $param ) { @@ -1640,7 +1638,7 @@ class FileRepo { /** * Path disclosure protection function * - * @param $param string + * @param string $param * @return string */ function passThrough( $param ) { @@ -1650,6 +1648,7 @@ class FileRepo { /** * Create a new fatal error * + * @param $message * @return FileRepoStatus */ public function newFatal( $message /*, parameters...*/ ) { @@ -1662,7 +1661,7 @@ class FileRepo { /** * Create a new good result * - * @param $value null|string + * @param null|string $value * @return FileRepoStatus */ public function newGood( $value = null ) { @@ -1674,8 +1673,8 @@ class FileRepo { * title object. If not, return false. * STUB * - * @param $title Title of image - * @return Bool + * @param Title $title Title of image + * @return bool */ public function checkRedirect( Title $title ) { return false; @@ -1686,7 +1685,7 @@ class FileRepo { * Doesn't do anything for repositories that don't support image redirects. * * STUB - * @param $title Title of image + * @param Title $title Title of image */ public function invalidateImageRedirect( Title $title ) { } @@ -1797,7 +1796,7 @@ class FileRepo { /** * Get an UploadStash associated with this repo. * - * @param $user User + * @param User $user * @return UploadStash */ public function getUploadStash( User $user = null ) { diff --git a/includes/filerepo/FileRepoStatus.php b/includes/filerepo/FileRepoStatus.php index 56fddf4637..4be38bf287 100644 --- a/includes/filerepo/FileRepoStatus.php +++ b/includes/filerepo/FileRepoStatus.php @@ -54,7 +54,7 @@ class FileRepoStatus extends Status { } /** - * @param $repo FileRepo + * @param bool|FileRepo $repo */ function __construct( $repo = false ) { if ( $repo ) { diff --git a/includes/filerepo/ForeignAPIRepo.php b/includes/filerepo/ForeignAPIRepo.php index bb16c8bc3e..68846cf1cc 100644 --- a/includes/filerepo/ForeignAPIRepo.php +++ b/includes/filerepo/ForeignAPIRepo.php @@ -106,8 +106,8 @@ class ForeignAPIRepo extends FileRepo { * Per docs in FileRepo, this needs to return false if we don't support versioned * files. Well, we don't. * - * @param $title Title - * @param $time string|bool + * @param Title $title + * @param string|bool $time * @return File */ function newFile( $title, $time = false ) { @@ -119,7 +119,7 @@ class ForeignAPIRepo extends FileRepo { } /** - * @param $files array + * @param array $files * @return array */ function fileExistsBatch( array $files ) { @@ -174,7 +174,7 @@ class ForeignAPIRepo extends FileRepo { } /** - * @param $virtualUrl string + * @param string $virtualUrl * @return bool */ function getFileProps( $virtualUrl ) { @@ -182,7 +182,7 @@ class ForeignAPIRepo extends FileRepo { } /** - * @param $query array + * @param array $query * @return string */ function fetchImageQuery( $query ) { @@ -209,7 +209,7 @@ class ForeignAPIRepo extends FileRepo { } /** - * @param $data array + * @param array $data * @return bool|array */ function getImageInfo( $data ) { @@ -225,7 +225,7 @@ class ForeignAPIRepo extends FileRepo { } /** - * @param $hash string + * @param string $hash * @return array */ function findBySha1( $hash ) { @@ -249,11 +249,11 @@ class ForeignAPIRepo extends FileRepo { } /** - * @param $name string - * @param $width int - * @param $height int - * @param $result null - * @param $otherParams string + * @param string $name + * @param int $width + * @param int $height + * @param null $result + * @param string $otherParams * @return bool */ function getThumbUrl( $name, $width = -1, $height = -1, &$result = null, $otherParams = '' ) { @@ -277,10 +277,11 @@ class ForeignAPIRepo extends FileRepo { } /** - * @param $name string - * @param $width int - * @param $height int - * @param $otherParams string + * @param string $name + * @param int $width + * @param int $height + * @param string $otherParams + * @param string $lang Language code for language of error * @return bool|MediaTransformError * @since 1.22 */ @@ -318,8 +319,8 @@ class ForeignAPIRepo extends FileRepo { * Otherwise retrieve remote thumb url, check for local file. * * @param string $name is a dbkey form of a title - * @param $width - * @param $height + * @param int $width + * @param int $height * @param string $params Other rendering parameters (page number, etc) * from handler's makeParamString. * @return bool|string @@ -414,7 +415,7 @@ class ForeignAPIRepo extends FileRepo { /** * @see FileRepo::getZoneUrl() - * @param $zone String + * @param string $zone * @param string|null $ext Optional file extension * @return String */ @@ -431,7 +432,7 @@ class ForeignAPIRepo extends FileRepo { /** * Get the local directory corresponding to one of the basic zones - * @param $zone string + * @param string $zone * @return bool|null|string */ function getZonePath( $zone ) { @@ -492,9 +493,9 @@ class ForeignAPIRepo extends FileRepo { /** * Like a Http:get request, but with custom User-Agent. * @see Http:get - * @param $url string - * @param $timeout string - * @param $options array + * @param string $url + * @param string $timeout + * @param array $options * @return bool|String */ public static function httpGet( $url, $timeout = 'default', $options = array() ) { @@ -529,9 +530,10 @@ class ForeignAPIRepo extends FileRepo { /** * HTTP GET request to a mediawiki API (with caching) - * @param $target string Used in cache key creation, mostly - * @param $query array The query parameters for the API request - * @param $cacheTTL int Time to live for the memcached caching + * @param string $target Used in cache key creation, mostly + * @param array $query The query parameters for the API request + * @param int $cacheTTL Time to live for the memcached caching + * @return null */ public function httpGetCached( $target, $query, $cacheTTL = 3600 ) { if ( $this->mApiBase ) { @@ -568,7 +570,7 @@ class ForeignAPIRepo extends FileRepo { } /** - * @param $callback Array|string + * @param array|string $callback * @throws MWException */ function enumFiles( $callback ) { diff --git a/includes/filerepo/ForeignDBRepo.php b/includes/filerepo/ForeignDBRepo.php index b38416fc86..92f017f6c6 100644 --- a/includes/filerepo/ForeignDBRepo.php +++ b/includes/filerepo/ForeignDBRepo.php @@ -27,14 +27,28 @@ * @ingroup FileRepo */ class ForeignDBRepo extends LocalRepo { - # Settings + /** @var string */ protected $dbType; + + /** @var string */ protected $dbServer; + + /** @var string */ protected $dbUser; + + /** @var string */ protected $dbPassword; + + /** @var string */ protected $dbName; + + /** @var string */ protected $dbFlags; + + /** @var string */ protected $tablePrefix; + + /** @var bool */ protected $hasSharedCache; # Other stuff @@ -43,7 +57,7 @@ class ForeignDBRepo extends LocalRepo { protected $fileFromRowFactory = array( 'ForeignDBFile', 'newFromRow' ); /** - * @param $info array|null + * @param array|null $info */ function __construct( $info ) { parent::__construct( $info ); diff --git a/includes/filerepo/ForeignDBViaLBRepo.php b/includes/filerepo/ForeignDBViaLBRepo.php index ad6370624d..18f8d5df1c 100644 --- a/includes/filerepo/ForeignDBViaLBRepo.php +++ b/includes/filerepo/ForeignDBViaLBRepo.php @@ -27,14 +27,23 @@ * @ingroup FileRepo */ class ForeignDBViaLBRepo extends LocalRepo { + /** @var string */ protected $wiki; + + /** @var string */ protected $dbName; + + /** @var string */ protected $tablePrefix; + + /** @var array */ protected $fileFactory = array( 'ForeignDBFile', 'newFromTitle' ); + + /** @var array */ protected $fileFromRowFactory = array( 'ForeignDBFile', 'newFromRow' ); /** - * @param $info array|null + * @param array|null $info */ function __construct( $info ) { parent::__construct( $info ); diff --git a/includes/filerepo/LocalRepo.php b/includes/filerepo/LocalRepo.php index 965f677c73..d9f3c121bb 100644 --- a/includes/filerepo/LocalRepo.php +++ b/includes/filerepo/LocalRepo.php @@ -29,16 +29,27 @@ * @ingroup FileRepo */ class LocalRepo extends FileRepo { + /** @var array */ protected $fileFactory = array( 'LocalFile', 'newFromTitle' ); + + /** @var array */ protected $fileFactoryKey = array( 'LocalFile', 'newFromKey' ); + + /** @var array */ protected $fileFromRowFactory = array( 'LocalFile', 'newFromRow' ); + + /** @var array */ protected $oldFileFromRowFactory = array( 'OldLocalFile', 'newFromRow' ); + + /** @var array */ protected $oldFileFactory = array( 'OldLocalFile', 'newFromTitle' ); + + /** @var array */ protected $oldFileFactoryKey = array( 'OldLocalFile', 'newFromKey' ); /** * @throws MWException - * @param $row + * @param array $row * @return LocalFile */ function newFileFromRow( $row ) { @@ -52,8 +63,8 @@ class LocalRepo extends FileRepo { } /** - * @param $title - * @param $archiveName + * @param Title $title + * @param string $archiveName * @return OldLocalFile */ function newFromArchiveName( $title, $archiveName ) { @@ -66,7 +77,7 @@ class LocalRepo extends FileRepo { * interleave database locks with file operations, which is potentially a * remote operation. * - * @param $storageKeys array + * @param array $storageKeys * * @return FileRepoStatus */ @@ -155,7 +166,7 @@ class LocalRepo extends FileRepo { /** * Checks if there is a redirect named as $title * - * @param $title Title of file + * @param Title $title Title of file * @return bool */ function checkRedirect( Title $title ) { @@ -208,7 +219,7 @@ class LocalRepo extends FileRepo { * Function link Title::getArticleID(). * We can't say Title object, what database it should use, so we duplicate that function here. * - * @param $title Title + * @param Title $title * @return bool|int|mixed */ protected function getArticleID( $title ) { @@ -234,7 +245,7 @@ class LocalRepo extends FileRepo { * SHA-1 content hash. * * @param string $hash a sha1 hash to look for - * @return Array + * @return array */ function findBySha1( $hash ) { $dbr = $this->getSlaveDB(); @@ -349,7 +360,7 @@ class LocalRepo extends FileRepo { /** * Invalidates image redirect cache related to that image * - * @param $title Title of page + * @param Title $title Title of page * @return void */ function invalidateImageRedirect( Title $title ) { diff --git a/includes/filerepo/NullRepo.php b/includes/filerepo/NullRepo.php index 29e4cad97c..f2b7395c7b 100644 --- a/includes/filerepo/NullRepo.php +++ b/includes/filerepo/NullRepo.php @@ -26,9 +26,8 @@ * @ingroup FileRepo */ class NullRepo extends FileRepo { - /** - * @param $info array|null + * @param array|null $info */ function __construct( $info ) { } diff --git a/includes/filerepo/RepoGroup.php b/includes/filerepo/RepoGroup.php index 1a7ae3473c..f9b4fb491a 100644 --- a/includes/filerepo/RepoGroup.php +++ b/includes/filerepo/RepoGroup.php @@ -30,12 +30,16 @@ class RepoGroup { /** @var LocalRepo */ protected $localRepo; + /** @var array */ protected $foreignRepos; /** @var bool */ protected $reposInitialised = false; + /** @var array */ protected $localInfo; + + /** @var array */ protected $foreignInfo; /** @var array */ @@ -76,7 +80,7 @@ class RepoGroup { * It's not enough to just create a superclass ... you have * to get people to call into it even though all they know is RepoGroup::singleton() * - * @param $instance RepoGroup + * @param RepoGroup $instance */ static function setSingleton( $instance ) { self::$instance = $instance; @@ -87,9 +91,9 @@ class RepoGroup { * * @param array $localInfo Associative array for local repo's info * @param array $foreignInfo of repository info arrays. - * Each info array is an associative array with the 'class' member - * giving the class name. The entire array is passed to the repository - * constructor as the first parameter. + * Each info array is an associative array with the 'class' member + * giving the class name. The entire array is passed to the repository + * constructor as the first parameter. */ function __construct( $localInfo, $foreignInfo ) { $this->localInfo = $localInfo; @@ -103,18 +107,15 @@ class RepoGroup { * * @param $title Title|string Title object or string * @param array $options Associative array of options: - * time: requested time for an archived image, or false for the - * current version. An image object will be returned which was - * created at the specified time. - * - * ignoreRedirect: If true, do not follow file redirects - * - * private: If true, return restricted (deleted) files if the current - * user is allowed to view them. Otherwise, such files will not - * be found. - * - * bypassCache: If true, do not use the process-local cache of File objects - * @return File object or false if it is not found + * time: requested time for an archived image, or false for the + * current version. An image object will be returned which was + * created at the specified time. + * ignoreRedirect: If true, do not follow file redirects + * private: If true, return restricted (deleted) files if the current + * user is allowed to view them. Otherwise, such files will not + * be found. + * bypassCache: If true, do not use the process-local cache of File objects + * @return File|bool False if title is not found */ function findFile( $title, $options = array() ) { if ( !is_array( $options ) ) { @@ -173,7 +174,7 @@ class RepoGroup { } /** - * @param $inputItems array + * @param array $inputItems * @return array */ function findFiles( $inputItems ) { @@ -280,7 +281,7 @@ class RepoGroup { * Find all instances of files with this keys * * @param array $hashes base 36 SHA-1 hashes - * @return Array of array of File objects + * @return array of array of File objects */ function findBySha1s( array $hashes ) { if ( !$this->reposInitialised ) { @@ -301,7 +302,7 @@ class RepoGroup { /** * Get the repo instance with a given key. - * @param $index string|int + * @param string|int $index * @return bool|LocalRepo */ function getRepo( $index ) { @@ -319,7 +320,7 @@ class RepoGroup { /** * Get the repo instance by its name - * @param $name string + * @param string $name * @return bool */ function getRepoByName( $name ) { @@ -349,8 +350,8 @@ class RepoGroup { * Call a function for each foreign repo, with the repo object as the * first parameter. * - * @param $callback Callback: the function to call - * @param array $params optional additional parameters to pass to the function + * @param callable $callback The function to call + * @param array $params Optional additional parameters to pass to the function * @return bool */ function forEachForeignRepo( $callback, $params = array() ) { @@ -366,7 +367,7 @@ class RepoGroup { /** * Does the installation have any foreign repos set up? - * @return Boolean + * @return bool */ function hasForeignRepos() { return (bool)$this->foreignRepos; @@ -399,7 +400,7 @@ class RepoGroup { /** * Split a virtual URL into repo, zone and rel parts - * @param $url string + * @param string $url * @throws MWException * @return array containing repo, zone and rel */ @@ -417,7 +418,7 @@ class RepoGroup { } /** - * @param $fileName string + * @param string $fileName * @return array */ function getFileProps( $fileName ) { @@ -459,7 +460,7 @@ class RepoGroup { /** * Clear RepoGroup process cache used for finding a file - * @param $title Title|null Title of the file or null to clear all files + * @param Title|null $title Title of the file or null to clear all files */ public function clearCache( Title $title = null ) { if ( $title == null ) { diff --git a/includes/filerepo/file/ArchivedFile.php b/includes/filerepo/file/ArchivedFile.php index 91c2fb4f09..0d86c7078d 100644 --- a/includes/filerepo/file/ArchivedFile.php +++ b/includes/filerepo/file/ArchivedFile.php @@ -195,8 +195,7 @@ class ArchivedFile { /** * Loads a file object from the filearchive table * - * @param $row - * + * @param stdClass $row * @return ArchivedFile */ public static function newFromRow( $row ) { @@ -238,7 +237,7 @@ class ArchivedFile { /** * Load ArchivedFile object fields from a DB row. * - * @param $row Object database row + * @param stdClass $row Object database row * @since 1.21 */ public function loadFromRow( $row ) { @@ -539,7 +538,7 @@ class ArchivedFile { /** * for file or revision rows * - * @param $field Integer: one of DELETED_* bitfield constants + * @param int $field One of DELETED_* bitfield constants * @return bool */ public function isDeleted( $field ) { @@ -551,8 +550,8 @@ class ArchivedFile { /** * Determine if the current user is allowed to view a particular * field of this FileStore image file, if it's marked as deleted. - * @param $field Integer - * @param $user User object to check, or null to use $wgUser + * @param int $field + * @param null|User $user User object to check, or null to use $wgUser * @return bool */ public function userCan( $field, User $user = null ) { diff --git a/includes/filerepo/file/File.php b/includes/filerepo/file/File.php index cf4ddf512a..2fb3b220f6 100644 --- a/includes/filerepo/file/File.php +++ b/includes/filerepo/file/File.php @@ -156,8 +156,8 @@ abstract class File { * may return false or throw exceptions if they are not set. * Most subclasses will want to call assertRepoDefined() here. * - * @param $title Title|string|bool - * @param $repo FileRepo|bool + * @param Title|string|bool $title + * @param FileRepo|bool $repo */ function __construct( $title, $repo ) { if ( $title !== false ) { // subclasses may not use MW titles @@ -171,7 +171,7 @@ abstract class File { * Given a string or Title object return either a * valid Title object with namespace NS_FILE or null * - * @param $title Title|string + * @param Title|string $title * @param string|bool $exception Use 'exception' to throw an error on bad titles * @throws MWException * @return Title|null @@ -235,7 +235,7 @@ abstract class File { /** * Checks if file extensions are compatible * - * @param $old File Old file + * @param File $old Old file * @param string $new New name * * @return bool|null @@ -275,10 +275,9 @@ abstract class File { /** * Callback for usort() to do file sorts by name * - * @param $a File - * @param $b File - * - * @return Integer: result of name comparison + * @param File $a + * @param File $b + * @return int Result of name comparison */ public static function compare( File $a, File $b ) { return strcmp( $a->getName(), $b->getName() ); @@ -355,7 +354,7 @@ abstract class File { * Upload URL paths _may or may not_ be fully qualified, so * we check. Local paths are assumed to belong on $wgServer. * - * @return String + * @return string */ public function getFullUrl() { return wfExpandUrl( $this->getUrl(), PROTO_RELATIVE ); @@ -436,9 +435,8 @@ abstract class File { * STUB * Overridden by LocalFile, UnregisteredLocalFile * - * @param $page int - * - * @return number + * @param int $page + * @return int|bool */ public function getWidth( $page = 1 ) { return false; @@ -451,9 +449,8 @@ abstract class File { * STUB * Overridden by LocalFile, UnregisteredLocalFile * - * @param $page int - * - * @return bool|number False on failure + * @param int $page + * @return bool|int False on failure */ public function getHeight( $page = 1 ) { return false; @@ -464,7 +461,6 @@ abstract class File { * STUB * * @param string $type 'text' or 'id' - * * @return string|int */ public function getUser( $type = 'text' ) { @@ -474,7 +470,7 @@ abstract class File { /** * Get the duration of a media file in seconds * - * @return number + * @return int */ public function getLength() { $handler = $this->getHandler(); @@ -545,7 +541,7 @@ abstract class File { /** * Like getMetadata but returns a handler independent array of common values. * @see MediaHandler::getCommonMetaArray() - * @return Array or false if not supported + * @return array|bool Array or false if not supported * @since 1.23 */ public function getCommonMetaArray() { @@ -557,9 +553,10 @@ abstract class File { /** * get versioned metadata * - * @param $metadata Mixed Array or String of (serialized) metadata - * @param $version integer version number. - * @return Array containing metadata, or what was passed to it on fail (unserializing if not array) + * @param array|string $metadata Array or string of (serialized) metadata + * @param int $version Version number. + * @return array Array containing metadata, or what was passed to it on fail + * (unserializing if not array) */ public function convertMetadataVersion( $metadata, $version ) { $handler = $this->getHandler(); @@ -757,7 +754,7 @@ abstract class File { * * Overridden by LocalFile to avoid unnecessary stat calls. * - * @return boolean Whether file exists in the repository. + * @return bool Whether file exists in the repository. */ public function exists() { return $this->getPath() && $this->repo->fileExists( $this->path ); @@ -767,7 +764,7 @@ abstract class File { * Returns true if file exists in the repository and can be included in a page. * It would be unsafe to include private images, making public thumbnails inadvertently * - * @return boolean Whether file exists in the repository and is includable. + * @return bool Whether file exists in the repository and is includable. */ public function isVisible() { return $this->exists(); @@ -793,7 +790,7 @@ abstract class File { /** * Get a ThumbnailImage which is the same size as the source * - * @param $handlerParams array + * @param array $handlerParams * * @return string */ @@ -815,7 +812,7 @@ abstract class File { * Otherwise, the format may be "-" or "-thumbnail.". * * @param array $params handler-specific parameters - * @param $flags integer Bitfield that supports THUMB_* constants + * @param int $flags Bitfield that supports THUMB_* constants * @return string */ public function thumbName( $params, $flags = 0 ) { @@ -831,7 +828,6 @@ abstract class File { * * @param string $name * @param array $params Parameters which will be passed to MediaHandler::makeParamString - * * @return string */ public function generateThumbName( $name, $params ) { @@ -861,8 +857,8 @@ abstract class File { * specified, the generated image will be no bigger than width x height, * and will also have correct aspect ratio. * - * @param $width Integer: maximum width of the generated thumbnail - * @param $height Integer: maximum height of the image (optional) + * @param int $width Maximum width of the generated thumbnail + * @param int $height Maximum height of the image (optional) * * @return string */ @@ -884,8 +880,8 @@ abstract class File { * * @param string $thumbPath Thumbnail storage path * @param string $thumbUrl Thumbnail URL - * @param $params Array - * @param $flags integer + * @param array $params + * @param int $flags * @return MediaTransformOutput */ protected function transformErrorOutput( $thumbPath, $thumbUrl, $params, $flags ) { @@ -904,8 +900,8 @@ abstract class File { * Transform a media file * * @param array $params an associative array of handler-specific parameters. - * Typical keys are width, height and page. - * @param $flags Integer: a bitfield, may contain self::RENDER_NOW to force rendering + * Typical keys are width, height and page. + * @param int $flags A bitfield, may contain self::RENDER_NOW to force rendering * @return MediaTransformOutput|bool False on failure */ function transform( $params, $flags = 0 ) { @@ -1053,7 +1049,8 @@ abstract class File { /** * Get a MediaHandler instance for this file * - * @return MediaHandler|boolean Registered MediaHandler for file's mime type or false if none found + * @return MediaHandler|bool Registered MediaHandler for file's MIME type + * or false if none found */ function getHandler() { if ( !isset( $this->handler ) ) { @@ -1108,7 +1105,7 @@ abstract class File { * STUB * Overridden by LocalFile * @param array $options Options, which include: - * 'forThumbRefresh' : The purging is only to refresh thumbnails + * 'forThumbRefresh' : The purging is only to refresh thumbnails */ function purgeCache( $options = array() ) { } @@ -1147,7 +1144,7 @@ abstract class File { * Return a fragment of the history of file. * * STUB - * @param $limit integer Limit of rows to return + * @param int $limit Limit of rows to return * @param string $start timestamp Only revisions older than $start will be returned * @param string $end timestamp Only revisions newer than $end will be returned * @param bool $inc Include the endpoints of the time range @@ -1229,7 +1226,6 @@ abstract class File { * thumbnail directory or a particular file if $suffix is specified * * @param bool|string $suffix if not false, the name of a thumbnail file - * * @return string */ function getThumbRel( $suffix = false ) { @@ -1257,7 +1253,6 @@ abstract class File { * * @param string $archiveName the timestamped name of an archived image * @param bool|string $suffix if not false, the name of a thumbnail file - * * @return string */ function getArchiveThumbRel( $archiveName, $suffix = false ) { @@ -1275,7 +1270,6 @@ abstract class File { * Get the path of the archived file. * * @param bool|string $suffix if not false, the name of an archived file. - * * @return string */ function getArchivePath( $suffix = false ) { @@ -1289,7 +1283,6 @@ abstract class File { * * @param string $archiveName the timestamped name of an archived image * @param bool|string $suffix if not false, the name of a thumbnail file - * * @return string */ function getArchiveThumbPath( $archiveName, $suffix = false ) { @@ -1302,8 +1295,7 @@ abstract class File { /** * Get the path of the thumbnail directory, or a particular file if $suffix is specified * - * @param bool|string $suffix if not false, the name of a thumbnail file - * + * @param bool|string $suffix If not false, the name of a thumbnail file * @return string */ function getThumbPath( $suffix = false ) { @@ -1315,8 +1307,7 @@ abstract class File { /** * Get the path of the transcoded directory, or a particular file if $suffix is specified * - * @param bool|string $suffix if not false, the name of a media file - * + * @param bool|string $suffix If not false, the name of a media file * @return string */ function getTranscodedPath( $suffix = false ) { @@ -1328,8 +1319,7 @@ abstract class File { /** * Get the URL of the archive directory, or a particular file if $suffix is specified * - * @param bool|string $suffix if not false, the name of an archived file - * + * @param bool|string $suffix If not false, the name of an archived file * @return string */ function getArchiveUrl( $suffix = false ) { @@ -1349,8 +1339,7 @@ abstract class File { * Get the URL of the archived file's thumbs, or a particular thumb if $suffix is specified * * @param string $archiveName the timestamped name of an archived image - * @param bool|string $suffix if not false, the name of a thumbnail file - * + * @param bool|string $suffix If not false, the name of a thumbnail file * @return string */ function getArchiveThumbUrl( $archiveName, $suffix = false ) { @@ -1371,8 +1360,7 @@ abstract class File { * Get the URL of the zone directory, or a particular file if $suffix is specified * * @param string $zone name of requested zone - * @param bool|string $suffix if not false, the name of a file in zone - * + * @param bool|string $suffix If not false, the name of a file in zone * @return string path */ function getZoneUrl( $zone, $suffix = false ) { @@ -1390,7 +1378,6 @@ abstract class File { * Get the URL of the thumbnail directory, or a particular file if $suffix is specified * * @param bool|string $suffix if not false, the name of a thumbnail file - * * @return string path */ function getThumbUrl( $suffix = false ) { @@ -1400,8 +1387,7 @@ abstract class File { /** * Get the URL of the transcoded directory, or a particular file if $suffix is specified * - * @param bool|string $suffix if not false, the name of a media file - * + * @param bool|string $suffix If not false, the name of a media file * @return string path */ function getTranscodedUrl( $suffix = false ) { @@ -1411,8 +1397,7 @@ abstract class File { /** * Get the public zone virtual URL for a current version source file * - * @param bool|string $suffix if not false, the name of a thumbnail file - * + * @param bool|string $suffix If not false, the name of a thumbnail file * @return string */ function getVirtualUrl( $suffix = false ) { @@ -1428,8 +1413,7 @@ abstract class File { /** * Get the public zone virtual URL for an archived version source file * - * @param bool|string $suffix if not false, the name of a thumbnail file - * + * @param bool|string $suffix If not false, the name of a thumbnail file * @return string */ function getArchiveVirtualUrl( $suffix = false ) { @@ -1447,8 +1431,7 @@ abstract class File { /** * Get the virtual URL for a thumbnail file or directory * - * @param bool|string $suffix if not false, the name of a thumbnail file - * + * @param bool|string $suffix If not false, the name of a thumbnail file * @return string */ function getThumbVirtualUrl( $suffix = false ) { @@ -1483,12 +1466,12 @@ abstract class File { * Overridden by LocalFile * @param $oldver * @param $desc - * @param $license string - * @param $copyStatus string - * @param $source string - * @param $watch bool - * @param $timestamp string|bool - * @param $user User object or null to use $wgUser + * @param string $license + * @param string $copyStatus + * @param string $source + * @param bool $watch + * @param string|bool $timestamp + * @param null|User $user User object or null to use $wgUser * @return bool * @throws MWException */ @@ -1510,12 +1493,11 @@ abstract class File { * - headers : name/value map of HTTP headers to use in response to GET/HEAD requests * * @param string $srcPath local filesystem path to the source image - * @param $flags Integer: a bitwise combination of: - * File::DELETE_SOURCE Delete the source file, i.e. move - * rather than copy + * @param int $flags A bitwise combination of: + * File::DELETE_SOURCE Delete the source file, i.e. move rather than copy * @param array $options Optional additional parameters * @return FileRepoStatus object. On success, the value member contains the - * archive name, or an empty string if it was a new file. + * archive name, or an empty string if it was a new file. * * STUB * Overridden by LocalFile @@ -1576,8 +1558,7 @@ abstract class File { * Is this file a "deleted" file in a private archive? * STUB * - * @param integer $field one of DELETED_* bitfield constants - * + * @param int $field one of DELETED_* bitfield constants * @return bool */ function isDeleted( $field ) { @@ -1613,7 +1594,7 @@ abstract class File { * Cache purging is done; checks for validity * and logging are caller's responsibility * - * @param $target Title New file name + * @param Title $target New file name * @return FileRepoStatus object. */ function move( $target ) { @@ -1628,8 +1609,8 @@ abstract class File { * * Cache purging is done; logging is caller's responsibility. * - * @param $reason String - * @param $suppress Boolean: hide content from sysops? + * @param string $reason + * @param bool $suppress Hide content from sysops? * @return bool on success, false on some kind of failure * STUB * Overridden by LocalFile @@ -1645,10 +1626,10 @@ abstract class File { * May throw database exceptions on error. * * @param array $versions set of record ids of deleted items to restore, - * or empty to restore all revisions. + * or empty to restore all revisions. * @param bool $unsuppress remove restrictions on content upon restoration? * @return int|bool the number of file revisions restored if successful, - * or false on failure + * or false on failure * STUB * Overridden by LocalFile */ @@ -1661,7 +1642,7 @@ abstract class File { * e.g. DJVU or PDF. Note that this may be true even if the file in * question only has a single page. * - * @return Bool + * @return bool */ function isMultipage() { return $this->getHandler() && $this->handler->isMultiPage( $this ); @@ -1688,9 +1669,9 @@ abstract class File { /** * Calculate the height of a thumbnail using the source and destination width * - * @param $srcWidth - * @param $srcHeight - * @param $dstWidth + * @param int $srcWidth + * @param int $srcHeight + * @param int $dstWidth * * @return int */ @@ -1708,7 +1689,7 @@ abstract class File { * can't be determined. * * @param string $fileName The filename - * @return Array + * @return array */ function getImageSize( $fileName ) { if ( !$this->getHandler() ) { @@ -1735,7 +1716,7 @@ abstract class File { /** * Get the HTML text of the description page, if available * - * @param $lang Language Optional language to fetch description in + * @param bool|Language $lang Optional language to fetch description in * @return string */ function getDescriptionText( $lang = false ) { @@ -1780,12 +1761,12 @@ abstract class File { * Get description of file revision * STUB * - * @param $audience Integer: one of: - * File::FOR_PUBLIC to be displayed to all users - * File::FOR_THIS_USER to be displayed to the given user - * File::RAW get the description regardless of permissions - * @param $user User object to check for, only if FOR_THIS_USER is passed - * to the $audience parameter + * @param int $audience One of: + * File::FOR_PUBLIC to be displayed to all users + * File::FOR_THIS_USER to be displayed to the given user + * File::RAW get the description regardless of permissions + * @param User $user User object to check for, only if FOR_THIS_USER is + * passed to the $audience parameter * @return string */ function getDescription( $audience = self::FOR_PUBLIC, User $user = null ) { @@ -1834,9 +1815,9 @@ abstract class File { * Determine if the current user is allowed to view a particular * field of this file, if it's marked as deleted. * STUB - * @param $field Integer - * @param $user User object to check, or null to use $wgUser - * @return Boolean + * @param int $field + * @param User $user User object to check, or null to use $wgUser + * @return bool */ function userCan( $field, User $user = null ) { return true; @@ -1846,8 +1827,8 @@ abstract class File { * Get an associative array containing information about a file in the local filesystem. * * @param string $path absolute local filesystem path - * @param $ext Mixed: the file extension, or true to extract it from the filename. - * Set it to false to ignore the extension. + * @param string|bool $ext The file extension, or true to extract it from + * the filename. Set it to false to ignore the extension. * * @return array * @deprecated since 1.19 @@ -1869,7 +1850,6 @@ abstract class File { * fairly neatly. * * @param $path string - * * @return bool|string False on failure * @deprecated since 1.19 */ @@ -1882,7 +1862,7 @@ abstract class File { } /** - * @return Array HTTP header name/value map to use for HEAD/GET request responses + * @return array HTTP header name/value map to use for HEAD/GET request responses */ function getStreamHeaders() { $handler = $this->getHandler(); @@ -1930,7 +1910,7 @@ abstract class File { } /** - * @return + * @return string */ function getRedirected() { return $this->redirected; @@ -1952,7 +1932,7 @@ abstract class File { } /** - * @param $from + * @param string $from * @return void */ function redirectedFrom( $from ) { @@ -1968,7 +1948,7 @@ abstract class File { /** * Check if this file object is small and can be cached - * @return boolean + * @return bool */ public function isCacheable() { return true; diff --git a/includes/filerepo/file/ForeignAPIFile.php b/includes/filerepo/file/ForeignAPIFile.php index 2f713a9cf7..690d1b854b 100644 --- a/includes/filerepo/file/ForeignAPIFile.php +++ b/includes/filerepo/file/ForeignAPIFile.php @@ -34,7 +34,7 @@ class ForeignAPIFile extends File { /** * @param $title - * @param $repo ForeignApiRepo + * @param ForeignApiRepo $repo * @param $info * @param bool $exists */ @@ -48,8 +48,8 @@ class ForeignAPIFile extends File { } /** - * @param $title Title - * @param $repo ForeignApiRepo + * @param Title $title + * @param ForeignApiRepo $repo * @return ForeignAPIFile|null */ static function newFromTitle( Title $title, $repo ) { @@ -150,7 +150,7 @@ class ForeignAPIFile extends File { // Info we can get from API... /** - * @param $page int + * @param int $page * @return int|number */ public function getWidth( $page = 1 ) { @@ -158,7 +158,7 @@ class ForeignAPIFile extends File { } /** - * @param $page int + * @param int $page * @return int */ public function getHeight( $page = 1 ) { @@ -177,7 +177,8 @@ class ForeignAPIFile extends File { } /** - * @return array|null extended metadata (see imageinfo API for format) or null on error + * @return array|null Extended metadata (see imageinfo API for format) or + * null on error */ public function getExtendedMetadata() { if ( isset( $this->mInfo['extmetadata'] ) ) { @@ -188,7 +189,7 @@ class ForeignAPIFile extends File { } /** - * @param $metadata array + * @param array $metadata * @return array */ public static function parseMetadata( $metadata ) { @@ -226,6 +227,8 @@ class ForeignAPIFile extends File { } /** + * @param int $audience + * @param User $user * @return null|string */ public function getDescription( $audience = self::FOR_PUBLIC, User $user = null ) { @@ -242,7 +245,7 @@ class ForeignAPIFile extends File { } /** - * @return bool|Mixed|string + * @return bool|string */ function getTimestamp() { return wfTimestamp( TS_MW, @@ -287,7 +290,7 @@ class ForeignAPIFile extends File { /** * Only useful if we're locally caching thumbs anyway... - * @param $suffix string + * @param string $suffix * @return null|string */ function getThumbPath( $suffix = '' ) { @@ -336,7 +339,7 @@ class ForeignAPIFile extends File { } /** - * @param $options array + * @param array $options */ function purgeThumbnails( $options = array() ) { global $wgMemc; diff --git a/includes/filerepo/file/ForeignDBFile.php b/includes/filerepo/file/ForeignDBFile.php index b7a5c35fe6..36558c4c9b 100644 --- a/includes/filerepo/file/ForeignDBFile.php +++ b/includes/filerepo/file/ForeignDBFile.php @@ -28,9 +28,9 @@ */ class ForeignDBFile extends LocalFile { /** - * @param $title - * @param $repo - * @param $unused + * @param Title $title + * @param FileRepo $repo + * @param null $unused * @return ForeignDBFile */ static function newFromTitle( $title, $repo, $unused = null ) { @@ -41,9 +41,8 @@ class ForeignDBFile extends LocalFile { * Create a ForeignDBFile from a title * Do not call this except from inside a repo class. * - * @param $row - * @param $repo - * + * @param stdClass $row + * @param FileRepo $repo * @return ForeignDBFile */ static function newFromRow( $row, $repo ) { @@ -55,10 +54,10 @@ class ForeignDBFile extends LocalFile { } /** - * @param $srcPath String - * @param $flags int - * @param $options Array - * @return \FileRepoStatus + * @param string $srcPath + * @param int $flags + * @param array $options + * @return FileRepoStatus * @throws MWException */ function publish( $srcPath, $flags = 0, array $options = array() ) { @@ -83,9 +82,9 @@ class ForeignDBFile extends LocalFile { } /** - * @param $versions array - * @param $unsuppress bool - * @return \FileRepoStatus + * @param array $versions + * @param bool $unsuppress + * @return FileRepoStatus * @throws MWException */ function restore( $versions = array(), $unsuppress = false ) { @@ -93,9 +92,9 @@ class ForeignDBFile extends LocalFile { } /** - * @param $reason string - * @param $suppress bool - * @return \FileRepoStatus + * @param string $reason + * @param bool $suppress + * @return FileRepoStatus * @throws MWException */ function delete( $reason, $suppress = false ) { @@ -103,8 +102,8 @@ class ForeignDBFile extends LocalFile { } /** - * @param $target Title - * @return \FileRepoStatus + * @param Title $target + * @return FileRepoStatus * @throws MWException */ function move( $target ) { @@ -120,7 +119,7 @@ class ForeignDBFile extends LocalFile { } /** - * @param $lang Language Optional language to fetch description in. + * @param bool|Language $lang Optional language to fetch description in. * @return string */ function getDescriptionText( $lang = false ) { diff --git a/includes/filerepo/file/LocalFile.php b/includes/filerepo/file/LocalFile.php index 191642f360..1f9190be95 100644 --- a/includes/filerepo/file/LocalFile.php +++ b/includes/filerepo/file/LocalFile.php @@ -129,8 +129,8 @@ class LocalFile extends File { * * Note: $unused param is only here to avoid an E_STRICT * - * @param $title - * @param $repo + * @param Title $title + * @param FileRepo $repo * @param $unused * * @return LocalFile @@ -143,8 +143,8 @@ class LocalFile extends File { * Create a LocalFile from a title * Do not call this except from inside a repo class. * - * @param $row - * @param $repo + * @param stdClass $row + * @param FileRepo $repo * * @return LocalFile */ @@ -161,9 +161,8 @@ class LocalFile extends File { * Do not call this except from inside a repo class. * * @param string $sha1 base-36 SHA-1 - * @param $repo LocalRepo + * @param LocalRepo $repo * @param string|bool $timestamp MW_timestamp (optional) - * * @return bool|LocalFile */ static function newFromKey( $sha1, $repo, $timestamp = false ) { @@ -348,6 +347,7 @@ class LocalFile extends File { } /** + * @param string $prefix * @return array */ function getLazyCacheFields( $prefix = 'img_' ) { @@ -430,9 +430,10 @@ class LocalFile extends File { } /** - * @param Row $row - * @param $prefix string - * @return Array + * @param array $row Row + * @param string $prefix + * @throws MWException + * @return array */ protected function unprefixRow( $row, $prefix = 'img_' ) { $array = (array)$row; @@ -647,7 +648,7 @@ class LocalFile extends File { /** * Return the width of the image * - * @param $page int + * @param int $page * @return int */ public function getWidth( $page = 1 ) { @@ -674,7 +675,7 @@ class LocalFile extends File { /** * Return the height of the image * - * @param $page int + * @param int $page * @return int */ public function getHeight( $page = 1 ) { @@ -733,7 +734,7 @@ class LocalFile extends File { } /** - * Return the size of the image file, in bytes + * Returns the size of the image file, in bytes * @return int */ public function getSize() { @@ -753,7 +754,7 @@ class LocalFile extends File { } /** - * Return the type of the media in the file. + * Returns the type of the media in the file. * Use the value returned by this function with the MEDIATYPE_xxx constants. * @return string */ @@ -771,7 +772,7 @@ class LocalFile extends File { /** * Returns true if the file exists on disk. - * @return boolean Whether file exist on disk. + * @return bool Whether file exist on disk. */ public function exists() { $this->load(); @@ -787,9 +788,9 @@ class LocalFile extends File { /** * Fix thumbnail files from 1.4 or before, with extreme prejudice - * @todo : do we still care about this? Perhaps a maintenance script - * can be made instead. Enabling this code results in a serious - * RTT regression for wikis without 404 handling. + * @todo Do we still care about this? Perhaps a maintenance script + * can be made instead. Enabling this code results in a serious + * RTT regression for wikis without 404 handling. */ function migrateThumbFile( $thumbName ) { /* Old code for bug 2532 @@ -875,7 +876,7 @@ class LocalFile extends File { /** * Delete all previously generated thumbnails, refresh metadata in memcached and purge the squid. * - * @param Array $options An array potentially with the key forThumbRefresh. + * @param array $options An array potentially with the key forThumbRefresh. * * @note This used to purge old thumbnails by default as well, but doesn't anymore. */ @@ -894,7 +895,7 @@ class LocalFile extends File { /** * Delete cached transformed files for an archived version only. - * @param string $archiveName name of the archived file + * @param string $archiveName Name of the archived file */ function purgeOldThumbnails( $archiveName ) { global $wgUseSquid; @@ -962,8 +963,8 @@ class LocalFile extends File { /** * Delete a list of thumbnails visible at urls - * @param string $dir base dir of the files. - * @param array $files of strings: relative filenames (to $dir) + * @param string $dir Base dir of the files. + * @param array $files Array of strings: relative filenames (to $dir) */ protected function purgeThumbList( $dir, $files ) { $fileListDebug = strtr( @@ -993,10 +994,10 @@ class LocalFile extends File { /** purgeEverything inherited */ /** - * @param $limit null - * @param $start null - * @param $end null - * @param $inc bool + * @param int $limit Optional: Limit to number of results + * @param int $start Optional: Timestamp, start from + * @param int $end Optional: Timestamp, end at + * @param bool $inc * @return array */ function getHistory( $limit = null, $start = null, $end = null, $inc = true ) { @@ -1042,7 +1043,7 @@ class LocalFile extends File { } /** - * Return the history of this file, line by line. + * Returns the history of this file, line by line. * starts with current version, then old versions. * uses $this->historyLine to check which line to return: * 0 return line for current version @@ -1110,16 +1111,17 @@ class LocalFile extends File { /** * Upload a file and record it in the DB - * @param string $srcPath source storage path, virtual URL, or filesystem path - * @param string $comment upload description - * @param string $pageText text to use for the new description page, - * if a new description page is created - * @param $flags Integer|bool: flags for publish() - * @param array|bool $props File properties, if known. This can be used to reduce the - * upload time when uploading virtual URLs for which the file info - * is already known - * @param string|bool $timestamp timestamp for img_timestamp, or false to use the current time - * @param $user User|null: User object or null to use $wgUser + * @param string $srcPath Source storage path, virtual URL, or filesystem path + * @param string $comment Upload description + * @param string $pageText Text to use for the new description page, + * if a new description page is created + * @param int|bool $flags Flags for publish() + * @param array|bool $props File properties, if known. This can be used to + * reduce the upload time when uploading virtual URLs for which the file + * info is already known + * @param string|bool $timestamp Timestamp for img_timestamp, or false to use the + * current time + * @param User|null $user User object or null to use $wgUser * * @return FileRepoStatus object. On success, the value member contains the * archive name, or an empty string if it was a new file. @@ -1178,14 +1180,14 @@ class LocalFile extends File { /** * Record a file upload in the upload log and the image table - * @param $oldver - * @param $desc string - * @param $license string - * @param $copyStatus string - * @param $source string - * @param $watch bool - * @param $timestamp string|bool - * @param $user User object or null to use $wgUser + * @param string $oldver + * @param string $desc + * @param string $license + * @param string $copyStatus + * @param string $source + * @param bool $watch + * @param string|bool $timestamp + * @param User|null $user User object or null to use $wgUser * @return bool */ function recordUpload( $oldver, $desc, $license = '', $copyStatus = '', $source = '', @@ -1210,12 +1212,12 @@ class LocalFile extends File { /** * Record a file upload in the upload log and the image table - * @param $oldver - * @param $comment string - * @param $pageText string - * @param $props bool|array - * @param $timestamp bool|string - * @param $user null|User + * @param string $oldver + * @param string $comment + * @param string $pageText + * @param bool|array $props + * @param string|bool $timestamp + * @param null|User $user * @return bool */ function recordUpload2( @@ -1480,11 +1482,11 @@ class LocalFile extends File { * The archive name should be passed through to recordUpload for database * registration. * - * @param string $srcPath local filesystem path to the source image - * @param $flags Integer: a bitwise combination of: + * @param string $srcPath Local filesystem path to the source image + * @param int $flags A bitwise combination of: * File::DELETE_SOURCE Delete the source file, i.e. move rather than copy * @param array $options Optional additional parameters - * @return FileRepoStatus object. On success, the value member contains the + * @return FileRepoStatus On success, the value member contains the * archive name, or an empty string if it was a new file. */ function publish( $srcPath, $flags = 0, array $options = array() ) { @@ -1498,12 +1500,12 @@ class LocalFile extends File { * The archive name should be passed through to recordUpload for database * registration. * - * @param string $srcPath local filesystem path to the source image - * @param string $dstRel target relative path - * @param $flags Integer: a bitwise combination of: + * @param string $srcPath Local filesystem path to the source image + * @param string $dstRel Target relative path + * @param int $flags A bitwise combination of: * File::DELETE_SOURCE Delete the source file, i.e. move rather than copy * @param array $options Optional additional parameters - * @return FileRepoStatus object. On success, the value member contains the + * @return FileRepoStatus On success, the value member contains the * archive name, or an empty string if it was a new file. */ function publishTo( $srcPath, $dstRel, $flags = 0, array $options = array() ) { @@ -1543,8 +1545,8 @@ class LocalFile extends File { * Cache purging is done; checks for validity * and logging are caller's responsibility * - * @param $target Title New file name - * @return FileRepoStatus object. + * @param Title $target New file name + * @return FileRepoStatus */ function move( $target ) { if ( $this->getRepo()->getReadOnlyReason() !== false ) { @@ -1596,9 +1598,9 @@ class LocalFile extends File { * * Cache purging is done; logging is caller's responsibility. * - * @param $reason - * @param $suppress - * @return FileRepoStatus object. + * @param string $reason + * @param bool $suppress + * @return FileRepoStatus */ function delete( $reason, $suppress = false ) { if ( $this->getRepo()->getReadOnlyReason() !== false ) { @@ -1652,11 +1654,11 @@ class LocalFile extends File { * * Cache purging is done; logging is caller's responsibility. * - * @param $archiveName String - * @param $reason String - * @param $suppress Boolean - * @throws MWException or FSException on database or file store failure - * @return FileRepoStatus object. + * @param string $archiveName + * @param string $reason + * @param bool $suppress + * @throws MWException Exception on database or file store failure + * @return FileRepoStatus */ function deleteOld( $archiveName, $reason, $suppress = false ) { global $wgUseSquid; @@ -1692,8 +1694,8 @@ class LocalFile extends File { * May throw database exceptions on error. * * @param array $versions set of record ids of deleted items to restore, - * or empty to restore all revisions. - * @param $unsuppress Boolean + * or empty to restore all revisions. + * @param bool $unsuppress * @return FileRepoStatus */ function restore( $versions = array(), $unsuppress = false ) { @@ -1728,7 +1730,7 @@ class LocalFile extends File { /** * Get the URL of the file description page. - * @return String + * @return string */ function getDescriptionUrl() { return $this->title->getLocalURL(); @@ -1739,7 +1741,7 @@ class LocalFile extends File { * This is not used by ImagePage for local files, since (among other things) * it skips the parser cache. * - * @param $lang Language What language to get description in (Optional) + * @param Language $lang What language to get description in (Optional) * @return bool|mixed */ function getDescriptionText( $lang = null ) { @@ -1757,6 +1759,8 @@ class LocalFile extends File { } /** + * @param int $audience + * @param User $user * @return string */ function getDescription( $audience = self::FOR_PUBLIC, User $user = null ) { @@ -1820,7 +1824,8 @@ class LocalFile extends File { /** * Start a transaction and lock the image for update * Increments a reference counter if the lock is already held - * @return boolean True if the image exists, false otherwise + * @throws MWException + * @return bool True if the image exists, false otherwise */ function lock() { $dbw = $this->repo->getMasterDB(); @@ -1888,7 +1893,6 @@ class LocalFile extends File { * @ingroup FileAbstraction */ class LocalFileDeleteBatch { - /** @var LocalFile */ private $file; @@ -1911,9 +1915,9 @@ class LocalFileDeleteBatch { private $status; /** - * @param $file File - * @param $reason string - * @param $suppress bool + * @param File $file + * @param string $reason + * @param bool $suppress */ function __construct( File $file, $reason = '', $suppress = false ) { $this->file = $file; @@ -1927,7 +1931,7 @@ class LocalFileDeleteBatch { } /** - * @param $oldName string + * @param string $oldName */ function addOld( $oldName ) { $this->srcRels[$oldName] = $this->file->getArchiveRel( $oldName ); @@ -1936,7 +1940,7 @@ class LocalFileDeleteBatch { /** * Add the old versions of the image to the batch - * @return Array List of archive names from old versions + * @return array List of archive names from old versions */ function addOlds() { $archiveNames = array(); @@ -2263,8 +2267,8 @@ class LocalFileRestoreBatch { private $unsuppress = false; /** - * @param $file File - * @param $unsuppress bool + * @param File $file + * @param bool $unsuppress */ function __construct( File $file, $unsuppress = false ) { $this->file = $file; @@ -2530,7 +2534,7 @@ class LocalFileRestoreBatch { /** * Removes non-existent files from a store batch. - * @param $triplets array + * @param array $triplets * @return array */ function removeNonexistentFiles( $triplets ) { @@ -2552,7 +2556,7 @@ class LocalFileRestoreBatch { /** * Removes non-existent files from a cleanup batch. - * @param $batch array + * @param array $batch * @return array */ function removeNonexistentFromCleanup( $batch ) { @@ -2639,9 +2643,7 @@ class LocalFileMoveBatch { /** @var */ protected $archive; - /** - * @var DatabaseBase - */ + /** @var DatabaseBase */ protected $db; /** @@ -2669,7 +2671,7 @@ class LocalFileMoveBatch { /** * Add the old versions of the image to the batch - * @return Array List of archive names from old versions + * @return array List of archive names from old versions */ function addOlds() { $archiveBase = 'archive'; @@ -2846,7 +2848,7 @@ class LocalFileMoveBatch { /** * Removes non-existent files from move batch. - * @param $triplets array + * @param array $triplets * @return array */ function removeNonexistentFiles( $triplets ) { diff --git a/includes/filerepo/file/OldLocalFile.php b/includes/filerepo/file/OldLocalFile.php index ae4ad1ca54..d6c6a3c62f 100644 --- a/includes/filerepo/file/OldLocalFile.php +++ b/includes/filerepo/file/OldLocalFile.php @@ -37,9 +37,9 @@ class OldLocalFile extends LocalFile { const MAX_CACHE_ROWS = 20; /** - * @param $title Title - * @param $repo FileRepo - * @param $time null + * @param Title $title + * @param FileRepo $repo + * @param null|int $time Timestamp or null * @return OldLocalFile * @throws MWException */ @@ -53,9 +53,9 @@ class OldLocalFile extends LocalFile { } /** - * @param $title Title - * @param $repo FileRepo - * @param $archiveName + * @param Title $title + * @param FileRepo $repo + * @param string $archiveName * @return OldLocalFile */ static function newFromArchiveName( $title, $repo, $archiveName ) { @@ -63,8 +63,8 @@ class OldLocalFile extends LocalFile { } /** - * @param $row - * @param $repo FileRepo + * @param stdClass $row + * @param FileRepo $repo * @return OldLocalFile */ static function newFromRow( $row, $repo ) { @@ -80,7 +80,7 @@ class OldLocalFile extends LocalFile { * Do not call this except from inside a repo class. * * @param string $sha1 base-36 SHA-1 - * @param $repo LocalRepo + * @param LocalRepo $repo * @param string|bool $timestamp MW_timestamp (optional) * * @return bool|OldLocalFile @@ -127,9 +127,9 @@ class OldLocalFile extends LocalFile { } /** - * @param $title Title - * @param $repo FileRepo - * @param string $time timestamp or null to load by archive name + * @param Title $title + * @param FileRepo $repo + * @param string $time Timestamp or null to load by archive name * @param string $archiveName archive name or null to load by timestamp * @throws MWException */ @@ -150,7 +150,7 @@ class OldLocalFile extends LocalFile { } /** - * @return String + * @return string */ function getArchiveName() { if ( !isset( $this->archive_name ) ) { @@ -233,7 +233,7 @@ class OldLocalFile extends LocalFile { } /** - * @param $prefix string + * @param string $prefix * @return array */ function getCacheFields( $prefix = 'img_' ) { @@ -294,8 +294,8 @@ class OldLocalFile extends LocalFile { } /** - * @param $field Integer: one of DELETED_* bitfield constants - * for file or revision rows + * @param int $field One of DELETED_* bitfield constants for file or + * revision rows * @return bool */ function isDeleted( $field ) { @@ -318,8 +318,8 @@ class OldLocalFile extends LocalFile { * Determine if the current user is allowed to view a particular * field of this image file, if it's marked as deleted. * - * @param $field Integer - * @param $user User object to check, or null to use $wgUser + * @param int $field + * @param User|null $user User object to check, or null to use $wgUser * @return bool */ function userCan( $field, User $user = null ) { @@ -333,12 +333,11 @@ class OldLocalFile extends LocalFile { * * @param string $srcPath File system path of the source file * @param string $archiveName Full archive name of the file, in the form - * $timestamp!$filename, where $filename must match $this->getName() - * - * @param $timestamp string - * @param $comment string - * @param $user - * @param $flags int + * $timestamp!$filename, where $filename must match $this->getName() + * @param string $timestamp + * @param string $comment + * @param User $user + * @param int $flags * @return FileRepoStatus */ function uploadOld( $srcPath, $archiveName, $timestamp, $comment, $user, $flags = 0 ) { @@ -365,9 +364,9 @@ class OldLocalFile extends LocalFile { * * @param string $srcPath File system path to the source file * @param string $archiveName The archive name of the file - * @param $timestamp string + * @param string $timestamp * @param string $comment Upload comment - * @param $user User User who did this upload + * @param User $user User who did this upload * @return bool */ function recordOldUpload( $srcPath, $archiveName, $timestamp, $comment, $user ) { diff --git a/includes/filerepo/file/UnregisteredLocalFile.php b/includes/filerepo/file/UnregisteredLocalFile.php index 6d0786dcad..782e23ac5b 100644 --- a/includes/filerepo/file/UnregisteredLocalFile.php +++ b/includes/filerepo/file/UnregisteredLocalFile.php @@ -54,7 +54,7 @@ class UnregisteredLocalFile extends File { /** * @param string $path Storage path - * @param $mime string + * @param string $mime * @return UnregisteredLocalFile */ static function newFromPath( $path, $mime ) { @@ -62,8 +62,8 @@ class UnregisteredLocalFile extends File { } /** - * @param $title - * @param $repo + * @param Title $title + * @param FileRepo $repo * @return UnregisteredLocalFile */ static function newFromTitle( $title, $repo ) { @@ -75,10 +75,10 @@ class UnregisteredLocalFile extends File { * A FileRepo object is not required here, unlike most other File classes. * * @throws MWException - * @param $title Title|bool - * @param $repo FileRepo|bool - * @param $path string|bool - * @param $mime string|bool + * @param Title|bool $title + * @param FileRepo|bool $repo + * @param string|bool $path + * @param string|bool $mime */ function __construct( $title = false, $repo = false, $path = false, $mime = false ) { if ( !( $title && $repo ) && !$path ) { @@ -107,7 +107,7 @@ class UnregisteredLocalFile extends File { } /** - * @param $page int + * @param int $page * @return bool */ private function cachePageDimensions( $page = 1 ) { @@ -122,8 +122,8 @@ class UnregisteredLocalFile extends File { } /** - * @param $page int - * @return number + * @param int $page + * @return int */ function getWidth( $page = 1 ) { $dim = $this->cachePageDimensions( $page ); @@ -132,8 +132,8 @@ class UnregisteredLocalFile extends File { } /** - * @param $page int - * @return number + * @param int $page + * @return int */ function getHeight( $page = 1 ) { $dim = $this->cachePageDimensions( $page ); @@ -154,8 +154,8 @@ class UnregisteredLocalFile extends File { } /** - * @param $filename String - * @return Array|bool + * @param string $filename + * @return array|bool */ function getImageSize( $filename ) { if ( !$this->getHandler() ) { @@ -206,7 +206,7 @@ class UnregisteredLocalFile extends File { * The file at the path of $fsFile should not be deleted (or at least * not until the end of the request). This is mostly a performance hack. * - * @param $fsFile FSFile + * @param FSFile $fsFile * @return void */ public function setLocalReference( FSFile $fsFile ) { -- 2.20.1