r89102 MediaWiki - Code Review archive

Repository:MediaWiki
Revision:r89101‎ | r89102 | r89103 >
Date:13:33, 29 May 2011
Author:reedy
Status:ok
Tags:
Comment:
More documentation for File
Modified paths:
  • /trunk/phase3/includes/filerepo/File.php (modified) (history)

Diff [purge]

Index: trunk/phase3/includes/filerepo/File.php
@@ -117,6 +117,8 @@
118118 *
119119 * @param $old File Old file
120120 * @param $new string New name
 121+ *
 122+ * @return bool|null
121123 */
122124 static function checkExtensionCompatibility( File $old, $new ) {
123125 $oldMime = $old->getMimeType();
@@ -151,6 +153,8 @@
152154
153155 /**
154156 * Return the name of this file
 157+ *
 158+ * @return string
155159 */
156160 public function getName() {
157161 if ( !isset( $this->name ) ) {
@@ -161,6 +165,8 @@
162166
163167 /**
164168 * Get the file extension, e.g. "svg"
 169+ *
 170+ * @return string
165171 */
166172 function getExtension() {
167173 if ( !isset( $this->extension ) ) {
@@ -179,15 +185,20 @@
180186
181187 /**
182188 * Return the title used to find this file
 189+ *
 190+ * @return Title
183191 */
184192 public function getOriginalTitle() {
185 - if ( $this->redirected )
 193+ if ( $this->redirected ) {
186194 return $this->getRedirectedTitle();
 195+ }
187196 return $this->title;
188197 }
189198
190199 /**
191200 * Return the URL of the file
 201+ *
 202+ * @return string
192203 */
193204 public function getUrl() {
194205 if ( !isset( $this->url ) ) {
@@ -207,12 +218,14 @@
208219 return wfExpandUrl( $this->getUrl() );
209220 }
210221
 222+ /**
 223+ * @return string
 224+ */
211225 function getViewURL() {
212226 if( $this->mustRender()) {
213227 if( $this->canRender() ) {
214228 return $this->createThumb( $this->getWidth() );
215 - }
216 - else {
 229+ } else {
217230 wfDebug(__METHOD__.': supposed to render '.$this->getName().' ('.$this->getMimeType()."), but can't!\n");
218231 return $this->getURL(); #hm... return NULL?
219232 }
@@ -231,6 +244,8 @@
232245 *
233246 * Most callers don't check the return value, but ForeignAPIFile::getPath
234247 * returns false.
 248+ *
 249+ * @return string|false
235250 */
236251 public function getPath() {
237252 if ( !isset( $this->path ) ) {
@@ -240,10 +255,12 @@
241256 }
242257
243258 /**
244 - * Alias for getPath()
245 - *
246 - * @deprecated since 1.18 Use getPath().
247 - */
 259+ * Alias for getPath()
 260+ *
 261+ * @deprecated since 1.18 Use getPath().
 262+ *
 263+ * @return string
 264+ */
248265 public function getFullPath() {
249266 wfDeprecated( __METHOD__ );
250267 return $this->getPath();
@@ -255,8 +272,14 @@
256273 *
257274 * STUB
258275 * Overridden by LocalFile, UnregisteredLocalFile
 276+ *
 277+ * @param $page int
 278+ *
 279+ * @return number
259280 */
260 - public function getWidth( $page = 1 ) { return false; }
 281+ public function getWidth( $page = 1 ) {
 282+ return false;
 283+ }
261284
262285 /**
263286 * Return the height of the image. Returns false if the height is unknown
@@ -265,7 +288,9 @@
266289 * STUB
267290 * Overridden by LocalFile, UnregisteredLocalFile
268291 */
269 - public function getHeight( $page = 1 ) { return false; }
 292+ public function getHeight( $page = 1 ) {
 293+ return false;
 294+ }
270295
271296 /**
272297 * Returns ID or name of user who uploaded the file
@@ -273,10 +298,14 @@
274299 *
275300 * @param $type string 'text' or 'id'
276301 */
277 - public function getUser( $type='text' ) { return null; }
 302+ public function getUser( $type='text' ) {
 303+ return null;
 304+ }
278305
279306 /**
280307 * Get the duration of a media file in seconds
 308+ *
 309+ * @return number
281310 */
282311 public function getLength() {
283312 $handler = $this->getHandler();
@@ -289,6 +318,8 @@
290319
291320 /**
292321 * Return true if the file is vectorized
 322+ *
 323+ * @retur bool
293324 */
294325 public function isVectorized() {
295326 $handler = $this->getHandler();
@@ -299,7 +330,6 @@
300331 }
301332 }
302333
303 -
304334 /**
305335 * Get handler-specific metadata
306336 * Overridden by LocalFile, UnregisteredLocalFile
@@ -345,6 +375,8 @@
346376 * Returns the mime type of the file.
347377 * Overridden by LocalFile, UnregisteredLocalFile
348378 * STUB
 379+ *
 380+ * @return string
349381 */
350382 function getMimeType() { return 'unknown/unknown'; }
351383
@@ -365,6 +397,8 @@
366398 * that can be converted to a format
367399 * supported by all browsers (namely GIF, PNG and JPEG),
368400 * or if it is an SVG image and SVG conversion is enabled.
 401+ *
 402+ * @return bool
369403 */
370404 function canRender() {
371405 if ( !isset( $this->canRender ) ) {
@@ -396,6 +430,8 @@
397431
398432 /**
399433 * Alias for canRender()
 434+ *
 435+ * @return bool
400436 */
401437 function allowInlineDisplay() {
402438 return $this->canRender();
@@ -411,6 +447,8 @@
412448 *
413449 * Note that this function will always return true if allowInlineDisplay()
414450 * or isTrustedFile() is true for this file.
 451+ *
 452+ * @return bool
415453 */
416454 function isSafeFile() {
417455 if ( !isset( $this->isSafeFile ) ) {
@@ -426,34 +464,49 @@
427465
428466 /** Uncached accessor */
429467 protected function _getIsSafeFile() {
430 - if ($this->allowInlineDisplay()) return true;
431 - if ($this->isTrustedFile()) return true;
 468+ if ( $this->allowInlineDisplay() ) {
 469+ return true;
 470+ }
 471+ if ($this->isTrustedFile()) {
 472+ return true;
 473+ }
432474
433475 global $wgTrustedMediaFormats;
434476
435 - $type= $this->getMediaType();
436 - $mime= $this->getMimeType();
 477+ $type = $this->getMediaType();
 478+ $mime = $this->getMimeType();
437479 #wfDebug("LocalFile::isSafeFile: type= $type, mime= $mime\n");
438480
439 - if (!$type || $type===MEDIATYPE_UNKNOWN) return false; #unknown type, not trusted
440 - if ( in_array( $type, $wgTrustedMediaFormats) ) return true;
 481+ if ( !$type || $type === MEDIATYPE_UNKNOWN ) {
 482+ return false; #unknown type, not trusted
 483+ }
 484+ if ( in_array( $type, $wgTrustedMediaFormats ) ) {
 485+ return true;
 486+ }
441487
442 - if ($mime==="unknown/unknown") return false; #unknown type, not trusted
443 - if ( in_array( $mime, $wgTrustedMediaFormats) ) return true;
 488+ if ( $mime === "unknown/unknown" ) {
 489+ return false; #unknown type, not trusted
 490+ }
 491+ if ( in_array( $mime, $wgTrustedMediaFormats) ) {
 492+ return true;
 493+ }
444494
445495 return false;
446496 }
447497
448 - /** Returns true if the file is flagged as trusted. Files flagged that way
449 - * can be linked to directly, even if that is not allowed for this type of
450 - * file normally.
451 - *
452 - * This is a dummy function right now and always returns false. It could be
453 - * implemented to extract a flag from the database. The trusted flag could be
454 - * set on upload, if the user has sufficient privileges, to bypass script-
455 - * and html-filters. It may even be coupled with cryptographics signatures
456 - * or such.
457 - */
 498+ /**
 499+ * Returns true if the file is flagged as trusted. Files flagged that way
 500+ * can be linked to directly, even if that is not allowed for this type of
 501+ * file normally.
 502+ *
 503+ * This is a dummy function right now and always returns false. It could be
 504+ * implemented to extract a flag from the database. The trusted flag could be
 505+ * set on upload, if the user has sufficient privileges, to bypass script-
 506+ * and html-filters. It may even be coupled with cryptographics signatures
 507+ * or such.
 508+ *
 509+ * @return bool
 510+ */
458511 function isTrustedFile() {
459512 #this could be implemented to check a flag in the databas,
460513 #look for signatures, etc
@@ -481,6 +534,9 @@
482535 return $this->exists();
483536 }
484537
 538+ /**
 539+ * @return string
 540+ */
485541 function getTransformScript() {
486542 if ( !isset( $this->transformScript ) ) {
487543 $this->transformScript = false;
@@ -496,6 +552,10 @@
497553
498554 /**
499555 * Get a ThumbnailImage which is the same size as the source
 556+ *
 557+ * @param $handlerParams array
 558+ *
 559+ * @return string
500560 */
501561 function getUnscaledThumb( $handlerParams = array() ) {
502562 $hp =& $handlerParams;
@@ -513,6 +573,8 @@
514574 *
515575 * @param $params Array: handler-specific parameters
516576 * @private -ish
 577+ *
 578+ * @return string
517579 */
518580 function thumbName( $params ) {
519581 return $this->generateThumbName( $this->getName(), $params );
@@ -523,6 +585,8 @@
524586 *
525587 * @param string $name
526588 * @param array $params Parameters which will be passed to MediaHandler::makeParamString
 589+ *
 590+ * @return string
527591 */
528592 function generateThumbName( $name, $params ) {
529593 if ( !$this->getHandler() ) {
@@ -551,6 +615,8 @@
552616 *
553617 * @param $width Integer: maximum width of the generated thumbnail
554618 * @param $height Integer: maximum height of the image (optional)
 619+ *
 620+ * @return string
555621 */
556622 public function createThumb( $width, $height = -1 ) {
557623 $params = array( 'width' => $width );
@@ -691,7 +757,9 @@
692758 * STUB
693759 * Overridden by LocalFile
694760 */
695 - function getThumbnails() { return array(); }
 761+ function getThumbnails() {
 762+ return array();
 763+ }
696764
697765 /**
698766 * Purge shared caches such as thumbnails and DB data caching
@@ -738,6 +806,8 @@
739807 * @param $start timestamp Only revisions older than $start will be returned
740808 * @param $end timestamp Only revisions newer than $end will be returned
741809 * @param $inc bool Include the endpoints of the time range
 810+ *
 811+ * @return array
742812 */
743813 function getHistory($limit = null, $start = null, $end = null, $inc=true) {
744814 return array();
@@ -767,6 +837,8 @@
768838 * Get the filename hash component of the directory including trailing slash,
769839 * e.g. f/fa/
770840 * If the repository is not hashed, returns an empty string.
 841+ *
 842+ * @return string
771843 */
772844 function getHashPath() {
773845 if ( !isset( $this->hashPath ) ) {
@@ -777,6 +849,8 @@
778850
779851 /**
780852 * Get the path of the file relative to the public zone root
 853+ *
 854+ * @return string
781855 */
782856 function getRel() {
783857 return $this->getHashPath() . $this->getName();
@@ -784,12 +858,20 @@
785859
786860 /**
787861 * Get urlencoded relative path of the file
 862+ *
 863+ * @return string
788864 */
789865 function getUrlRel() {
790866 return $this->getHashPath() . rawurlencode( $this->getName() );
791867 }
792868
793 - /** Get the relative path for an archive file */
 869+ /**
 870+ * Get the relative path for an archive file
 871+ *
 872+ * @param $suffix bool
 873+ *
 874+ * @return string
 875+ */
794876 function getArchiveRel( $suffix = false ) {
795877 $path = 'archive/' . $this->getHashPath();
796878 if ( $suffix === false ) {
@@ -800,12 +882,24 @@
801883 return $path;
802884 }
803885
804 - /** Get the path of the archive directory, or a particular file if $suffix is specified */
 886+ /**
 887+ * Get the path of the archive directory, or a particular file if $suffix is specified
 888+ *
 889+ * @param $suffix bool
 890+ *
 891+ * @return string
 892+ */
805893 function getArchivePath( $suffix = false ) {
806894 return $this->repo->getZonePath('public') . '/' . $this->getArchiveRel( $suffix );
807895 }
808896
809 - /** Get the path of the thumbnail directory, or a particular file if $suffix is specified */
 897+ /**
 898+ * Get the path of the thumbnail directory, or a particular file if $suffix is specified
 899+ *
 900+ * @param $suffix bool
 901+ *
 902+ * @return string
 903+ */
810904 function getThumbPath( $suffix = false ) {
811905 $path = $this->repo->getZonePath('thumb') . '/' . $this->getRel();
812906 if ( $suffix !== false ) {
@@ -814,7 +908,13 @@
815909 return $path;
816910 }
817911
818 - /** Get the URL of the archive directory, or a particular file if $suffix is specified */
 912+ /**
 913+ * Get the URL of the archive directory, or a particular file if $suffix is specified
 914+ *
 915+ * @param $suffix bool
 916+ *
 917+ * @return string
 918+ */
819919 function getArchiveUrl( $suffix = false ) {
820920 $path = $this->repo->getZoneUrl('public') . '/archive/' . $this->getHashPath();
821921 if ( $suffix === false ) {
@@ -825,7 +925,13 @@
826926 return $path;
827927 }
828928
829 - /** Get the URL of the thumbnail directory, or a particular file if $suffix is specified */
 929+ /**
 930+ * Get the URL of the thumbnail directory, or a particular file if $suffix is specified
 931+ *
 932+ * @param $suffix bool
 933+ *
 934+ * @return path
 935+ */
830936 function getThumbUrl( $suffix = false ) {
831937 $path = $this->repo->getZoneUrl('thumb') . '/' . $this->getUrlRel();
832938 if ( $suffix !== false ) {
@@ -834,7 +940,13 @@
835941 return $path;
836942 }
837943
838 - /** Get the virtual URL for an archive file or directory */
 944+ /**
 945+ * Get the virtual URL for an archive file or directory
 946+ *
 947+ * @param $suffix string
 948+ *
 949+ * @return string
 950+ */
839951 function getArchiveVirtualUrl( $suffix = false ) {
840952 $path = $this->repo->getVirtualUrl() . '/public/archive/' . $this->getHashPath();
841953 if ( $suffix === false ) {
@@ -845,7 +957,13 @@
846958 return $path;
847959 }
848960
849 - /** Get the virtual URL for a thumbnail file or directory */
 961+ /**
 962+ * Get the virtual URL for a thumbnail file or directory
 963+ *
 964+ * @param $suffix bool
 965+ *
 966+ * @return string
 967+ */
850968 function getThumbVirtualUrl( $suffix = false ) {
851969 $path = $this->repo->getVirtualUrl() . '/thumb/' . $this->getUrlRel();
852970 if ( $suffix !== false ) {
@@ -854,7 +972,13 @@
855973 return $path;
856974 }
857975
858 - /** Get the virtual URL for the file itself */
 976+ /**
 977+ * Get the virtual URL for the file itself
 978+ *
 979+ * @param $suffix bool
 980+ *
 981+ * @return string
 982+ */
859983 function getVirtualUrl( $suffix = false ) {
860984 $path = $this->repo->getVirtualUrl() . '/public/' . $this->getUrlRel();
861985 if ( $suffix !== false ) {
@@ -878,6 +1002,12 @@
8791003 * Record a file upload in the upload log and the image table
8801004 * STUB
8811005 * Overridden by LocalFile
 1006+ * @param $oldver
 1007+ * @param $desc
 1008+ * @param $license string
 1009+ * @param $copyStatus string
 1010+ * @param $source string
 1011+ * @param $watch bool
8821012 */
8831013 function recordUpload( $oldver, $desc, $license = '', $copyStatus = '', $source = '', $watch = false ) {
8841014 $this->readOnlyError();
@@ -905,6 +1035,9 @@
9061036 $this->readOnlyError();
9071037 }
9081038
 1039+ /**
 1040+ * @return bool
 1041+ */
9091042 function formatMetadata() {
9101043 if ( !$this->getHandler() ) {
9111044 return false;
@@ -931,8 +1064,10 @@
9321065 return $this->repo ? $this->repo->getName() : 'unknown';
9331066 }
9341067
935 - /*
 1068+ /**
9361069 * Returns the repository
 1070+ *
 1071+ * @return FileRepo
9371072 */
9381073 function getRepo() {
9391074 return $this->repo;
@@ -941,6 +1076,8 @@
9421077 /**
9431078 * Returns true if the image is an old version
9441079 * STUB
 1080+ *
 1081+ * @return bool
9451082 */
9461083 function isOld() {
9471084 return false;
@@ -949,6 +1086,10 @@
9501087 /**
9511088 * Is this file a "deleted" file in a private archive?
9521089 * STUB
 1090+ *
 1091+ * @param $field
 1092+ *
 1093+ * @return bool
9531094 */
9541095 function isDeleted( $field ) {
9551096 return false;
@@ -1012,15 +1153,15 @@
10131154 *
10141155 * May throw database exceptions on error.
10151156 *
1016 - * @param $versions set of record ids of deleted items to restore,
 1157+ * @param $versions array set of record ids of deleted items to restore,
10171158 * or empty to restore all revisions.
1018 - * @param $unsuppress remove restrictions on content upon restoration?
1019 - * @return the number of file revisions restored if successful,
 1159+ * @param $unsuppress bool remove restrictions on content upon restoration?
 1160+ * @return int|false the number of file revisions restored if successful,
10201161 * or false on failure
10211162 * STUB
10221163 * Overridden by LocalFile
10231164 */
1024 - function restore( $versions=array(), $unsuppress=false ) {
 1165+ function restore( $versions = array(), $unsuppress = false ) {
10251166 $this->readOnlyError();
10261167 }
10271168
@@ -1038,6 +1179,8 @@
10391180 /**
10401181 * Returns the number of pages of a multipage document, or false for
10411182 * documents which aren't multipage documents
 1183+ *
 1184+ * @return false|int
10421185 */
10431186 function pageCount() {
10441187 if ( !isset( $this->pageCount ) ) {
@@ -1052,6 +1195,12 @@
10531196
10541197 /**
10551198 * Calculate the height of a thumbnail using the source and destination width
 1199+ *
 1200+ * @param $srcWidth
 1201+ * @param $srcHeight
 1202+ * @param $dstWidth
 1203+ *
 1204+ * @return int
10561205 */
10571206 static function scaleHeight( $srcWidth, $srcHeight, $dstWidth ) {
10581207 // Exact integer multiply followed by division
@@ -1079,6 +1228,8 @@
10801229 /**
10811230 * Get the URL of the image description page. May return false if it is
10821231 * unknown or not applicable.
 1232+ *
 1233+ * @return string
10831234 */
10841235 function getDescriptionUrl() {
10851236 return $this->repo->getDescriptionUrl( $this->getName() );
@@ -1086,6 +1237,8 @@
10871238
10881239 /**
10891240 * Get the HTML text of the description page, if available
 1241+ *
 1242+ * @return string
10901243 */
10911244 function getDescriptionText() {
10921245 global $wgMemc, $wgLang;
@@ -1119,6 +1272,8 @@
11201273 /**
11211274 * Get discription of file revision
11221275 * STUB
 1276+ *
 1277+ * @return string
11231278 */
11241279 function getDescription() {
11251280 return null;
@@ -1127,6 +1282,8 @@
11281283 /**
11291284 * Get the 14-character timestamp of the file upload, or false if
11301285 * it doesn't exist
 1286+ *
 1287+ * @return string
11311288 */
11321289 function getTimestamp() {
11331290 $path = $this->getPath();
@@ -1138,6 +1295,8 @@
11391296
11401297 /**
11411298 * Get the SHA-1 base 36 hash of the file
 1299+ *
 1300+ * @return string
11421301 */
11431302 function getSha1() {
11441303 return self::sha1Base36( $this->getPath() );
@@ -1145,6 +1304,8 @@
11461305
11471306 /**
11481307 * Get the deletion archive key, <sha1>.<ext>
 1308+ *
 1309+ * @return string
11491310 */
11501311 function getStorageKey() {
11511312 $hash = $this->getSha1();
@@ -1173,6 +1334,8 @@
11741335 * @param $path String: absolute local filesystem path
11751336 * @param $ext Mixed: the file extension, or true to extract it from the filename.
11761337 * Set it to false to ignore the extension.
 1338+ *
 1339+ * @return array
11771340 */
11781341 static function getPropsFromPath( $path, $ext = true ) {
11791342 wfProfileIn( __METHOD__ );
@@ -1246,6 +1409,10 @@
12471410 * fairly neatly.
12481411 *
12491412 * Returns false on failure
 1413+ *
 1414+ * @param $path string
 1415+ *
 1416+ * @return false|string
12501417 */
12511418 static function sha1Base36( $path ) {
12521419 wfSuppressWarnings();
@@ -1258,6 +1425,9 @@
12591426 }
12601427 }
12611428
 1429+ /**
 1430+ * @return string
 1431+ */
12621432 function getLongDesc() {
12631433 $handler = $this->getHandler();
12641434 if ( $handler ) {
@@ -1267,6 +1437,9 @@
12681438 }
12691439 }
12701440
 1441+ /**
 1442+ * @return string
 1443+ */
12711444 function getShortDesc() {
12721445 $handler = $this->getHandler();
12731446 if ( $handler ) {
@@ -1276,6 +1449,9 @@
12771450 }
12781451 }
12791452
 1453+ /**
 1454+ * @return string
 1455+ */
12801456 function getDimensionsString() {
12811457 $handler = $this->getHandler();
12821458 if ( $handler ) {
@@ -1285,10 +1461,16 @@
12861462 }
12871463 }
12881464
 1465+ /**
 1466+ * @return
 1467+ */
12891468 function getRedirected() {
12901469 return $this->redirected;
12911470 }
12921471
 1472+ /**
 1473+ * @return Title
 1474+ */
12931475 function getRedirectedTitle() {
12941476 if ( $this->redirected ) {
12951477 if ( !$this->redirectTitle ) {
@@ -1298,10 +1480,17 @@
12991481 }
13001482 }
13011483
 1484+ /**
 1485+ * @param $from
 1486+ * @return void
 1487+ */
13021488 function redirectedFrom( $from ) {
13031489 $this->redirected = $from;
13041490 }
13051491
 1492+ /**
 1493+ * @return bool
 1494+ */
13061495 function isMissing() {
13071496 return false;
13081497 }

Status & tagging log