From e79af7c35f24f0c44406dab0a49a7855c54943f0 Mon Sep 17 00:00:00 2001 From: Sam Reed Date: Wed, 7 Sep 2011 12:00:58 +0000 Subject: [PATCH] Documentation Add explicit member variables Trim trailing whitespace --- includes/filerepo/ArchivedFile.php | 37 +++++++++++++++++ includes/filerepo/File.php | 29 +++++++++++--- includes/filerepo/FileRepo.php | 42 ++++++++++++++++--- includes/filerepo/ForeignAPIFile.php | 60 +++++++++++++++------------- includes/media/Generic.php | 2 + 5 files changed, 130 insertions(+), 40 deletions(-) diff --git a/includes/filerepo/ArchivedFile.php b/includes/filerepo/ArchivedFile.php index 0d9e349b4e..b62ed89b1e 100644 --- a/includes/filerepo/ArchivedFile.php +++ b/includes/filerepo/ArchivedFile.php @@ -177,6 +177,9 @@ class ArchivedFile { /** * Loads a file object from the filearchive table + * + * @param $row + * * @return ArchivedFile */ public static function newFromRow( $row ) { @@ -205,6 +208,8 @@ class ArchivedFile { /** * Return the associated title object + * + * @return Title */ public function getTitle() { return $this->title; @@ -212,16 +217,24 @@ class ArchivedFile { /** * Return the file name + * + * @return string */ public function getName() { return $this->name; } + /** + * @return int + */ public function getID() { $this->load(); return $this->id; } + /** + * @return bool + */ public function exists() { $this->load(); return $this->exists; @@ -229,6 +242,7 @@ class ArchivedFile { /** * Return the FileStore key + * @return string */ public function getKey() { $this->load(); @@ -237,6 +251,7 @@ class ArchivedFile { /** * Return the FileStore key (overriding base File class) + * @return string */ public function getStorageKey() { return $this->getKey(); @@ -244,6 +259,7 @@ class ArchivedFile { /** * Return the FileStore storage group + * @return string */ public function getGroup() { return $this->group; @@ -251,6 +267,7 @@ class ArchivedFile { /** * Return the width of the image + * @return int */ public function getWidth() { $this->load(); @@ -259,6 +276,7 @@ class ArchivedFile { /** * Return the height of the image + * @return int */ public function getHeight() { $this->load(); @@ -267,6 +285,7 @@ class ArchivedFile { /** * Get handler-specific metadata + * @return string */ public function getMetadata() { $this->load(); @@ -275,6 +294,7 @@ class ArchivedFile { /** * Return the size of the image file, in bytes + * @return int */ public function getSize() { $this->load(); @@ -283,6 +303,7 @@ class ArchivedFile { /** * Return the bits of the image file, in bytes + * @return int */ public function getBits() { $this->load(); @@ -291,6 +312,7 @@ class ArchivedFile { /** * Returns the mime type of the file. + * @return string */ public function getMimeType() { $this->load(); @@ -326,6 +348,7 @@ class ArchivedFile { /** * Return the type of the media in the file. * Use the value returned by this function with the MEDIATYPE_xxx constants. + * @return string */ public function getMediaType() { $this->load(); @@ -334,6 +357,8 @@ class ArchivedFile { /** * Return upload timestamp. + * + * @return string */ public function getTimestamp() { $this->load(); @@ -342,6 +367,8 @@ class ArchivedFile { /** * Return the user ID of the uploader. + * + * @return int */ public function getUser() { $this->load(); @@ -354,6 +381,8 @@ class ArchivedFile { /** * Return the user name of the uploader. + * + * @return string */ public function getUserText() { $this->load(); @@ -366,6 +395,8 @@ class ArchivedFile { /** * Return upload description. + * + * @return string */ public function getDescription() { $this->load(); @@ -378,6 +409,8 @@ class ArchivedFile { /** * Return the user ID of the uploader. + * + * @return int */ public function getRawUser() { $this->load(); @@ -386,6 +419,8 @@ class ArchivedFile { /** * Return the user name of the uploader. + * + * @return string */ public function getRawUserText() { $this->load(); @@ -394,6 +429,8 @@ class ArchivedFile { /** * Return upload description. + * + * @return string */ public function getRawDescription() { $this->load(); diff --git a/includes/filerepo/File.php b/includes/filerepo/File.php index 2e7b60513d..891a1e4e7f 100644 --- a/includes/filerepo/File.php +++ b/includes/filerepo/File.php @@ -70,8 +70,18 @@ abstract class File { */ protected $handler; + protected $url, $extension, $name, $path, $hashPath, $pageCount, $transformScript; + + /** + * @var bool + */ + protected $canRender, $isSafeFile; + /** * Call this constructor from child classes + * + * @param $title + * @param $repo */ function __construct( $title, $repo ) { $this->title = $title; @@ -117,7 +127,7 @@ abstract class File { * * @param $old File Old file * @param $new string New name - * + * * @return bool|null */ static function checkExtensionCompatibility( File $old, $new ) { @@ -217,7 +227,10 @@ abstract class File { public function getFullUrl() { return wfExpandUrl( $this->getUrl(), PROTO_RELATIVE ); } - + + /** + * @return string + */ public function getCanonicalUrl() { return wfExpandUrl( $this->getUrl(), PROTO_CANONICAL ); } @@ -292,6 +305,8 @@ abstract class File { * STUB * Overridden by LocalFile, UnregisteredLocalFile * + * @param $page int + * * @return false|number */ public function getHeight( $page = 1 ) { @@ -475,7 +490,7 @@ abstract class File { /** * Accessor for __get() - * + * * @return bool */ protected function getIsSafeFile() { @@ -891,10 +906,10 @@ abstract class File { /** * Get the relative path for an archived file - * + * * @param $suffix bool|string if not false, the name of an archived thumbnail file * - * @return string + * @return string */ function getArchiveRel( $suffix = false ) { $path = 'archive/' . $this->getHashPath(); @@ -909,9 +924,11 @@ abstract class File { /** * Get the relative path for an archived file's thumbs directory * or a specific thumb if the $suffix is given. - * + * * @param $archiveName string the timestamped name of an archived image * @param $suffix bool|string if not false, the name of a thumbnail file + * + * @return string */ function getArchiveThumbRel( $archiveName, $suffix = false ) { $path = 'archive/' . $this->getHashPath() . $archiveName . "/"; diff --git a/includes/filerepo/FileRepo.php b/includes/filerepo/FileRepo.php index 6d2f6e8a00..e1ded9e536 100644 --- a/includes/filerepo/FileRepo.php +++ b/includes/filerepo/FileRepo.php @@ -164,6 +164,8 @@ abstract class FileRepo { * $findItem = array( 'title' => $title, 'private' => true ); * $findBatch = array( $findItem ); * $repo->findFiles( $findBatch ); + * + * @return array */ function findFiles( $items ) { $result = array(); @@ -259,6 +261,8 @@ abstract class FileRepo { /** * Returns true if the repository can transform files via a 404 handler + * + * @return bool */ function canTransformVia404() { return $this->transformVia404; @@ -281,6 +285,11 @@ abstract class FileRepo { return $name; } + /** + * @param $name + * @param $levels + * @return string + */ static function getHashPathForLevel( $name, $levels ) { if ( $levels == 0 ) { return ''; @@ -297,6 +306,10 @@ abstract class FileRepo { /** * Get a relative path including trailing slash, e.g. f/fa/ * If the repo is not hashed, returns an empty string + * + * @param $name string + * + * @return string */ function getHashPath( $name ) { return self::getHashPathForLevel( $name, $this->hashLevels ); @@ -497,6 +510,11 @@ abstract class FileRepo { */ abstract function publishBatch( $triplets, $flags = 0 ); + /** + * @param $file + * @param int $flags + * @return bool + */ function fileExists( $file, $flags = 0 ) { $result = $this->fileExistsBatch( array( $file ), $flags ); return $result[0]; @@ -547,6 +565,8 @@ abstract class FileRepo { * Get properties of a file with a given virtual URL * The virtual URL must refer to this repo * Properties should ultimately be obtained via File::getPropsFromPath() + * + * @param $virtualUrl string */ abstract function getFileProps( $virtualUrl ); @@ -561,6 +581,10 @@ abstract class FileRepo { /** * Determine if a relative path is valid, i.e. not blank or involving directory traveral + * + * @param $filename string + * + * @return bool */ function validateFilename( $filename ) { if ( strval( $filename ) == '' ) { @@ -573,11 +597,11 @@ abstract class FileRepo { * Use the same traversal protection as Title::secureAndSplit() */ if ( strpos( $filename, '.' ) !== false && - ( $filename === '.' || $filename === '..' || - strpos( $filename, './' ) === 0 || - strpos( $filename, '../' ) === 0 || - strpos( $filename, '/./' ) !== false || - strpos( $filename, '/../' ) !== false ) ) + ( $filename === '.' || $filename === '..' || + strpos( $filename, './' ) === 0 || + strpos( $filename, '../' ) === 0 || + strpos( $filename, '/./' ) !== false || + strpos( $filename, '/../' ) !== false ) ) { return false; } else { @@ -589,6 +613,11 @@ abstract class FileRepo { * Path disclosure protection functions */ function paranoidClean( $param ) { return '[hidden]'; } + + /** + * @param $param + * @return + */ function passThrough( $param ) { return $param; } /** @@ -617,6 +646,8 @@ abstract class FileRepo { /** * Create a new good result + * + * @return FileRepoStatus */ function newGood( $value = null ) { return FileRepoStatus::newGood( $this, $value ); @@ -681,7 +712,6 @@ abstract class FileRepo { return $this->getName() == 'local'; } - /** * Get a key on the primary cache for this repository. * Returns false if the repository's cache is not accessible at this site. diff --git a/includes/filerepo/ForeignAPIFile.php b/includes/filerepo/ForeignAPIFile.php index 53c4a3bd47..ba699beec0 100644 --- a/includes/filerepo/ForeignAPIFile.php +++ b/includes/filerepo/ForeignAPIFile.php @@ -13,13 +13,13 @@ * @ingroup FileRepo */ class ForeignAPIFile extends File { - + private $mExists; /** - * @param $title - * @param $repo ForeignApiRepo - * @param $info + * @param $title + * @param $repo ForeignApiRepo + * @param $info * @param bool $exists */ function __construct( $title, $repo, $info, $exists = false ) { @@ -29,8 +29,8 @@ class ForeignAPIFile extends File { } /** - * @param $title Title - * @param $repo ForeignApiRepo + * @param $title Title + * @param $repo ForeignApiRepo * @return ForeignAPIFile|null */ static function newFromTitle( $title, $repo ) { @@ -61,19 +61,19 @@ class ForeignAPIFile extends File { return null; } } - + /** * Get the property string for iiprop and aiprop */ static function getProps() { return 'timestamp|user|comment|url|size|sha1|metadata|mime'; } - + // Dummy functions... public function exists() { return $this->mExists; } - + public function getPath() { return false; } @@ -100,18 +100,22 @@ class ForeignAPIFile extends File { public function getWidth( $page = 1 ) { return isset( $this->mInfo['width'] ) ? intval( $this->mInfo['width'] ) : 0; } - + + /** + * @param $page int + * @return int + */ public function getHeight( $page = 1 ) { return isset( $this->mInfo['height'] ) ? intval( $this->mInfo['height'] ) : 0; } - + public function getMetadata() { if ( isset( $this->mInfo['metadata'] ) ) { return serialize( self::parseMetadata( $this->mInfo['metadata'] ) ); } return null; } - + public static function parseMetadata( $metadata ) { if( !is_array( $metadata ) ) { return $metadata; @@ -122,11 +126,11 @@ class ForeignAPIFile extends File { } return $ret; } - + public function getSize() { return isset( $this->mInfo['size'] ) ? intval( $this->mInfo['size'] ) : null; } - + public function getUrl() { return isset( $this->mInfo['url'] ) ? strval( $this->mInfo['url'] ) : null; } @@ -134,25 +138,25 @@ class ForeignAPIFile extends File { public function getUser( $method='text' ) { return isset( $this->mInfo['user'] ) ? strval( $this->mInfo['user'] ) : null; } - + public function getDescription() { return isset( $this->mInfo['comment'] ) ? strval( $this->mInfo['comment'] ) : null; } function getSha1() { - return isset( $this->mInfo['sha1'] ) ? - wfBaseConvert( strval( $this->mInfo['sha1'] ), 16, 36, 31 ) : + return isset( $this->mInfo['sha1'] ) ? + wfBaseConvert( strval( $this->mInfo['sha1'] ), 16, 36, 31 ) : null; } - + function getTimestamp() { - return wfTimestamp( TS_MW, + return wfTimestamp( TS_MW, isset( $this->mInfo['timestamp'] ) ? - strval( $this->mInfo['timestamp'] ) : + strval( $this->mInfo['timestamp'] ) : null ); } - + function getMimeType() { if( !isset( $this->mInfo['mime'] ) ) { $magic = MimeMagic::singleton(); @@ -160,19 +164,19 @@ class ForeignAPIFile extends File { } return $this->mInfo['mime']; } - + /// @todo FIXME: May guess wrong on file types that can be eg audio or video function getMediaType() { $magic = MimeMagic::singleton(); return $magic->getMediaType( null, $this->getMimeType() ); } - + function getDescriptionUrl() { return isset( $this->mInfo['descriptionurl'] ) ? $this->mInfo['descriptionurl'] : false; } - + /** * Only useful if we're locally caching thumbs anyway... */ @@ -187,7 +191,7 @@ class ForeignAPIFile extends File { return null; } } - + function getThumbnails() { $files = array(); $dir = $this->getThumbPath( $this->getName() ); @@ -204,19 +208,19 @@ class ForeignAPIFile extends File { } return $files; } - + function purgeCache() { $this->purgeThumbnails(); $this->purgeDescriptionPage(); } - + function purgeDescriptionPage() { global $wgMemc, $wgContLang; $url = $this->repo->getDescriptionRenderUrl( $this->getName(), $wgContLang->getCode() ); $key = $this->repo->getLocalCacheKey( 'RemoteFileDescription', 'url', md5($url) ); $wgMemc->delete( $key ); } - + function purgeThumbnails() { global $wgMemc; $key = $this->repo->getLocalCacheKey( 'ForeignAPIRepo', 'ThumbUrl', $this->getName() ); diff --git a/includes/media/Generic.php b/includes/media/Generic.php index e22aad8789..cdc2cc0268 100644 --- a/includes/media/Generic.php +++ b/includes/media/Generic.php @@ -200,6 +200,8 @@ abstract class MediaHandler { * @param $dstUrl String: destination URL to use in output HTML * @param $params Array: arbitrary set of parameters validated by $this->validateParam() * @param $flags Integer: a bitfield, may contain self::TRANSFORM_LATER + * + * @return MediaTransformOutput */ abstract function doTransform( $image, $dstPath, $dstUrl, $params, $flags = 0 ); -- 2.20.1