includes/api/ApiQueryImageInfo.php

   1 <?php
   2 /**
   3  *
   4  *
   5  * Created on July 6, 2007
   6  *
   7  * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  */
  26
  27 /**
  28  * A query action to get image information and upload history.
  29  *
  30  * @ingroup API
  31  */
  32 class ApiQueryImageInfo extends ApiQueryBase {
  33         const TRANSFORM_LIMIT = 50;
  34         private static $transformCount = 0;
  35
  36         public function __construct( $query, $moduleName, $prefix = 'ii' ) {
  37                 // We allow a subclass to override the prefix, to create a related API
  38                 // module. Some other parts of MediaWiki construct this with a null
  39                 // $prefix, which used to be ignored when this only took two arguments
  40                 if ( is_null( $prefix ) ) {
  41                         $prefix = 'ii';
  42                 }
  43                 parent::__construct( $query, $moduleName, $prefix );
  44         }
  45
  46         public function execute() {
  47                 $params = $this->extractRequestParams();
  48
  49                 $prop = array_flip( $params['prop'] );
  50
  51                 $scale = $this->getScale( $params );
  52
  53                 $opts = array(
  54                         'version' => $params['metadataversion'],
  55                         'language' => $params['extmetadatalanguage'],
  56                         'multilang' => $params['extmetadatamultilang'],
  57                         'extmetadatafilter' => $params['extmetadatafilter'],
  58                         'revdelUser' => $this->getUser(),
  59                 );
  60
  61                 $pageIds = $this->getPageSet()->getAllTitlesByNamespace();
  62                 if ( !empty( $pageIds[NS_FILE] ) ) {
  63                         $titles = array_keys( $pageIds[NS_FILE] );
  64                         asort( $titles ); // Ensure the order is always the same
  65
  66                         $fromTitle = null;
  67                         if ( !is_null( $params['continue'] ) ) {
  68                                 $cont = explode( '|', $params['continue'] );
  69                                 $this->dieContinueUsageIf( count( $cont ) != 2 );
  70                                 $fromTitle = strval( $cont[0] );
  71                                 $fromTimestamp = $cont[1];
  72                                 // Filter out any titles before $fromTitle
  73                                 foreach ( $titles as $key => $title ) {
  74                                         if ( $title < $fromTitle ) {
  75                                                 unset( $titles[$key] );
  76                                         } else {
  77                                                 break;
  78                                         }
  79                                 }
  80                         }
  81
  82                         $user = $this->getUser();
  83                         $findTitles = array_map( function ( $title ) use ( $user ) {
  84                                 return array(
  85                                         'title' => $title,
  86                                         'private' => $user,
  87                                 );
  88                         }, $titles );
  89
  90                         if ( $params['localonly'] ) {
  91                                 $images = RepoGroup::singleton()->getLocalRepo()->findFiles( $findTitles );
  92                         } else {
  93                                 $images = RepoGroup::singleton()->findFiles( $findTitles );
  94                         }
  95
  96                         $result = $this->getResult();
  97                         foreach ( $titles as $title ) {
  98                                 $pageId = $pageIds[NS_FILE][$title];
  99                                 $start = $title === $fromTitle ? $fromTimestamp : $params['start'];
 100
 101                                 if ( !isset( $images[$title] ) ) {
 102                                         if ( isset( $prop['uploadwarning'] ) ) {
 103                                                 // Uploadwarning needs info about non-existing files
 104                                                 $images[$title] = wfLocalFile( $title );
 105                                         } else {
 106                                                 $result->addValue(
 107                                                         array( 'query', 'pages', intval( $pageId ) ),
 108                                                         'imagerepository', ''
 109                                                 );
 110                                                 // The above can't fail because it doesn't increase the result size
 111                                                 continue;
 112                                         }
 113                                 }
 114
 115                                 /** @var $img File */
 116                                 $img = $images[$title];
 117
 118                                 if ( self::getTransformCount() >= self::TRANSFORM_LIMIT ) {
 119                                         if ( count( $pageIds[NS_FILE] ) == 1 ) {
 120                                                 // See the 'the user is screwed' comment below
 121                                                 $this->setContinueEnumParameter( 'start',
 122                                                         $start !== null ? $start : wfTimestamp( TS_ISO_8601, $img->getTimestamp() )
 123                                                 );
 124                                         } else {
 125                                                 $this->setContinueEnumParameter( 'continue',
 126                                                         $this->getContinueStr( $img, $start ) );
 127                                         }
 128                                         break;
 129                                 }
 130
 131                                 $fit = $result->addValue(
 132                                         array( 'query', 'pages', intval( $pageId ) ),
 133                                         'imagerepository', $img->getRepoName()
 134                                 );
 135                                 if ( !$fit ) {
 136                                         if ( count( $pageIds[NS_FILE] ) == 1 ) {
 137                                                 // The user is screwed. imageinfo can't be solely
 138                                                 // responsible for exceeding the limit in this case,
 139                                                 // so set a query-continue that just returns the same
 140                                                 // thing again. When the violating queries have been
 141                                                 // out-continued, the result will get through
 142                                                 $this->setContinueEnumParameter( 'start',
 143                                                         $start !== null ? $start : wfTimestamp( TS_ISO_8601, $img->getTimestamp() )
 144                                                 );
 145                                         } else {
 146                                                 $this->setContinueEnumParameter( 'continue',
 147                                                         $this->getContinueStr( $img, $start ) );
 148                                         }
 149                                         break;
 150                                 }
 151
 152                                 // Check if we can make the requested thumbnail, and get transform parameters.
 153                                 $finalThumbParams = $this->mergeThumbParams( $img, $scale, $params['urlparam'] );
 154
 155                                 // Get information about the current version first
 156                                 // Check that the current version is within the start-end boundaries
 157                                 $gotOne = false;
 158                                 if (
 159                                         ( is_null( $start ) || $img->getTimestamp() <= $start ) &&
 160                                         ( is_null( $params['end'] ) || $img->getTimestamp() >= $params['end'] )
 161                                 ) {
 162                                         $gotOne = true;
 163
 164                                         $fit = $this->addPageSubItem( $pageId,
 165                                                 self::getInfo( $img, $prop, $result,
 166                                                         $finalThumbParams, $opts
 167                                                 )
 168                                         );
 169                                         if ( !$fit ) {
 170                                                 if ( count( $pageIds[NS_FILE] ) == 1 ) {
 171                                                         // See the 'the user is screwed' comment above
 172                                                         $this->setContinueEnumParameter( 'start',
 173                                                                 wfTimestamp( TS_ISO_8601, $img->getTimestamp() ) );
 174                                                 } else {
 175                                                         $this->setContinueEnumParameter( 'continue',
 176                                                                 $this->getContinueStr( $img ) );
 177                                                 }
 178                                                 break;
 179                                         }
 180                                 }
 181
 182                                 // Now get the old revisions
 183                                 // Get one more to facilitate query-continue functionality
 184                                 $count = ( $gotOne ? 1 : 0 );
 185                                 $oldies = $img->getHistory( $params['limit'] - $count + 1, $start, $params['end'] );
 186                                 /** @var $oldie File */
 187                                 foreach ( $oldies as $oldie ) {
 188                                         if ( ++$count > $params['limit'] ) {
 189                                                 // We've reached the extra one which shows that there are
 190                                                 // additional pages to be had. Stop here...
 191                                                 // Only set a query-continue if there was only one title
 192                                                 if ( count( $pageIds[NS_FILE] ) == 1 ) {
 193                                                         $this->setContinueEnumParameter( 'start',
 194                                                                 wfTimestamp( TS_ISO_8601, $oldie->getTimestamp() ) );
 195                                                 }
 196                                                 break;
 197                                         }
 198                                         $fit = self::getTransformCount() < self::TRANSFORM_LIMIT &&
 199                                                 $this->addPageSubItem( $pageId,
 200                                                         self::getInfo( $oldie, $prop, $result,
 201                                                                 $finalThumbParams, $opts
 202                                                         )
 203                                                 );
 204                                         if ( !$fit ) {
 205                                                 if ( count( $pageIds[NS_FILE] ) == 1 ) {
 206                                                         $this->setContinueEnumParameter( 'start',
 207                                                                 wfTimestamp( TS_ISO_8601, $oldie->getTimestamp() ) );
 208                                                 } else {
 209                                                         $this->setContinueEnumParameter( 'continue',
 210                                                                 $this->getContinueStr( $oldie ) );
 211                                                 }
 212                                                 break;
 213                                         }
 214                                 }
 215                                 if ( !$fit ) {
 216                                         break;
 217                                 }
 218                         }
 219                 }
 220         }
 221
 222         /**
 223          * From parameters, construct a 'scale' array
 224          * @param array $params Parameters passed to api.
 225          * @return Array or Null: key-val array of 'width' and 'height', or null
 226          */
 227         public function getScale( $params ) {
 228                 $p = $this->getModulePrefix();
 229
 230                 if ( $params['urlwidth'] != -1 ) {
 231                         $scale = array();
 232                         $scale['width'] = $params['urlwidth'];
 233                         $scale['height'] = $params['urlheight'];
 234                 } elseif ( $params['urlheight'] != -1 ) {
 235                         // Height is specified but width isn't
 236                         // Don't set $scale['width']; this signals mergeThumbParams() to fill it with the image's width
 237                         $scale = array();
 238                         $scale['height'] = $params['urlheight'];
 239                 } else {
 240                         $scale = null;
 241                         if ( $params['urlparam'] ) {
 242                                 $this->dieUsage( "{$p}urlparam requires {$p}urlwidth", "urlparam_no_width" );
 243                         }
 244                 }
 245
 246                 return $scale;
 247         }
 248
 249         /** Validate and merge scale parameters with handler thumb parameters, give error if invalid.
 250          *
 251          * We do this later than getScale, since we need the image
 252          * to know which handler, since handlers can make their own parameters.
 253          * @param File $image Image that params are for.
 254          * @param array $thumbParams thumbnail parameters from getScale
 255          * @param string $otherParams of otherParams (iiurlparam).
 256          * @return Array of parameters for transform.
 257          */
 258         protected function mergeThumbParams( $image, $thumbParams, $otherParams ) {
 259                 global $wgThumbLimits;
 260
 261                 if ( !isset( $thumbParams['width'] ) && isset( $thumbParams['height'] ) ) {
 262                         // We want to limit only by height in this situation, so pass the
 263                         // image's full width as the limiting width. But some file types
 264                         // don't have a width of their own, so pick something arbitrary so
 265                         // thumbnailing the default icon works.
 266                         if ( $image->getWidth() <= 0 ) {
 267                                 $thumbParams['width'] = max( $wgThumbLimits );
 268                         } else {
 269                                 $thumbParams['width'] = $image->getWidth();
 270                         }
 271                 }
 272
 273                 if ( !$otherParams ) {
 274                         return $thumbParams;
 275                 }
 276                 $p = $this->getModulePrefix();
 277
 278                 $h = $image->getHandler();
 279                 if ( !$h ) {
 280                         $this->setWarning( 'Could not create thumbnail because ' .
 281                                 $image->getName() . ' does not have an associated image handler' );
 282
 283                         return $thumbParams;
 284                 }
 285
 286                 $paramList = $h->parseParamString( $otherParams );
 287                 if ( !$paramList ) {
 288                         // Just set a warning (instead of dieUsage), as in many cases
 289                         // we could still render the image using width and height parameters,
 290                         // and this type of thing could happen between different versions of
 291                         // handlers.
 292                         $this->setWarning( "Could not parse {$p}urlparam for " . $image->getName()
 293                                 . '. Using only width and height' );
 294
 295                         return $thumbParams;
 296                 }
 297
 298                 if ( isset( $paramList['width'] ) ) {
 299                         if ( intval( $paramList['width'] ) != intval( $thumbParams['width'] ) ) {
 300                                 $this->setWarning( "Ignoring width value set in {$p}urlparam ({$paramList['width']}) "
 301                                         . "in favor of width value derived from {$p}urlwidth/{$p}urlheight "
 302                                         . "({$thumbParams['width']})" );
 303                         }
 304                 }
 305
 306                 foreach ( $paramList as $name => $value ) {
 307                         if ( !$h->validateParam( $name, $value ) ) {
 308                                 $this->dieUsage( "Invalid value for {$p}urlparam ($name=$value)", "urlparam" );
 309                         }
 310                 }
 311
 312                 return $thumbParams + $paramList;
 313         }
 314
 315         /**
 316          * Get result information for an image revision
 317          *
 318          * @param $file File object
 319          * @param array $prop of properties to get (in the keys)
 320          * @param $result ApiResult object
 321          * @param array $thumbParams containing 'width' and 'height' items, or null
 322          * @param array|bool|string $opts Options for data fetching.
 323          *   This is an array consisting of the keys:
 324          *    'version': The metadata version for the metadata option
 325          *    'language': The language for extmetadata property
 326          *    'multilang': Return all translations in extmetadata property
 327          *    'revdelUser': User to use when checking whether to show revision-deleted fields.
 328          * @return Array: result array
 329          */
 330         static function getInfo( $file, $prop, $result, $thumbParams = null, $opts = false ) {
 331                 global $wgContLang;
 332
 333                 $anyHidden = false;
 334
 335                 if ( !$opts || is_string( $opts ) ) {
 336                         $opts = array(
 337                                 'version' => $opts ?: 'latest',
 338                                 'language' => $wgContLang,
 339                                 'multilang' => false,
 340                                 'extmetadatafilter' => array(),
 341                                 'revdelUser' => null,
 342                         );
 343                 }
 344                 $version = $opts['version'];
 345                 $vals = array();
 346                 // Timestamp is shown even if the file is revdelete'd in interface
 347                 // so do same here.
 348                 if ( isset( $prop['timestamp'] ) ) {
 349                         $vals['timestamp'] = wfTimestamp( TS_ISO_8601, $file->getTimestamp() );
 350                 }
 351
 352                 // Handle external callers who don't pass revdelUser
 353                 if ( isset( $opts['revdelUser'] ) && $opts['revdelUser'] ) {
 354                         $revdelUser = $opts['revdelUser'];
 355                         $canShowField = function ( $field ) use ( $file, $revdelUser ) {
 356                                 return $file->userCan( $field, $revdelUser );
 357                         };
 358                 } else {
 359                         $canShowField = function ( $field ) use ( $file ) {
 360                                 return !$file->isDeleted( $field );
 361                         };
 362                 }
 363
 364                 $user = isset( $prop['user'] );
 365                 $userid = isset( $prop['userid'] );
 366
 367                 if ( $user || $userid ) {
 368                         if ( $file->isDeleted( File::DELETED_USER ) ) {
 369                                 $vals['userhidden'] = '';
 370                                 $anyHidden = true;
 371                         }
 372                         if ( $canShowField( File::DELETED_USER ) ) {
 373                                 if ( $user ) {
 374                                         $vals['user'] = $file->getUser();
 375                                 }
 376                                 if ( $userid ) {
 377                                         $vals['userid'] = $file->getUser( 'id' );
 378                                 }
 379                                 if ( !$file->getUser( 'id' ) ) {
 380                                         $vals['anon'] = '';
 381                                 }
 382                         }
 383                 }
 384
 385                 // This is shown even if the file is revdelete'd in interface
 386                 // so do same here.
 387                 if ( isset( $prop['size'] ) || isset( $prop['dimensions'] ) ) {
 388                         $vals['size'] = intval( $file->getSize() );
 389                         $vals['width'] = intval( $file->getWidth() );
 390                         $vals['height'] = intval( $file->getHeight() );
 391
 392                         $pageCount = $file->pageCount();
 393                         if ( $pageCount !== false ) {
 394                                 $vals['pagecount'] = $pageCount;
 395                         }
 396                 }
 397
 398                 $pcomment = isset( $prop['parsedcomment'] );
 399                 $comment = isset( $prop['comment'] );
 400
 401                 if ( $pcomment || $comment ) {
 402                         if ( $file->isDeleted( File::DELETED_COMMENT ) ) {
 403                                 $vals['commenthidden'] = '';
 404                                 $anyHidden = true;
 405                         }
 406                         if ( $canShowField( File::DELETED_COMMENT ) ) {
 407                                 if ( $pcomment ) {
 408                                         $vals['parsedcomment'] = Linker::formatComment(
 409                                                 $file->getDescription( File::RAW ), $file->getTitle() );
 410                                 }
 411                                 if ( $comment ) {
 412                                         $vals['comment'] = $file->getDescription( File::RAW );
 413                                 }
 414                         }
 415                 }
 416
 417                 $canonicaltitle = isset( $prop['canonicaltitle'] );
 418                 $url = isset( $prop['url'] );
 419                 $sha1 = isset( $prop['sha1'] );
 420                 $meta = isset( $prop['metadata'] );
 421                 $extmetadata = isset( $prop['extmetadata'] );
 422                 $commonmeta = isset( $prop['commonmetadata'] );
 423                 $mime = isset( $prop['mime'] );
 424                 $mediatype = isset( $prop['mediatype'] );
 425                 $archive = isset( $prop['archivename'] );
 426                 $bitdepth = isset( $prop['bitdepth'] );
 427                 $uploadwarning = isset( $prop['uploadwarning'] );
 428
 429                 if ( $uploadwarning ) {
 430                         $vals['html'] = SpecialUpload::getExistsWarning( UploadBase::getExistsWarning( $file ) );
 431                 }
 432
 433                 if ( $file->isDeleted( File::DELETED_FILE ) ) {
 434                         $vals['filehidden'] = '';
 435                         $anyHidden = true;
 436                 }
 437
 438                 if ( $anyHidden && $file->isDeleted( File::DELETED_RESTRICTED ) ) {
 439                         $vals['suppressed'] = true;
 440                 }
 441
 442                 if ( !$canShowField( File::DELETED_FILE ) ) {
 443                         //Early return, tidier than indenting all following things one level
 444                         return $vals;
 445                 }
 446
 447                 if ( $canonicaltitle ) {
 448                         $vals['canonicaltitle'] = $file->getTitle()->getPrefixedText();
 449                 }
 450
 451                 if ( $url ) {
 452                         if ( !is_null( $thumbParams ) ) {
 453                                 $mto = $file->transform( $thumbParams );
 454                                 self::$transformCount++;
 455                                 if ( $mto && !$mto->isError() ) {
 456                                         $vals['thumburl'] = wfExpandUrl( $mto->getUrl(), PROTO_CURRENT );
 457
 458                                         // bug 23834 - If the URL's are the same, we haven't resized it, so shouldn't give the wanted
 459                                         // thumbnail sizes for the thumbnail actual size
 460                                         if ( $mto->getUrl() !== $file->getUrl() ) {
 461                                                 $vals['thumbwidth'] = intval( $mto->getWidth() );
 462                                                 $vals['thumbheight'] = intval( $mto->getHeight() );
 463                                         } else {
 464                                                 $vals['thumbwidth'] = intval( $file->getWidth() );
 465                                                 $vals['thumbheight'] = intval( $file->getHeight() );
 466                                         }
 467
 468                                         if ( isset( $prop['thumbmime'] ) && $file->getHandler() ) {
 469                                                 list( , $mime ) = $file->getHandler()->getThumbType(
 470                                                         $mto->getExtension(), $file->getMimeType(), $thumbParams );
 471                                                 $vals['thumbmime'] = $mime;
 472                                         }
 473                                 } elseif ( $mto && $mto->isError() ) {
 474                                         $vals['thumberror'] = $mto->toText();
 475                                 }
 476                         }
 477                         $vals['url'] = wfExpandUrl( $file->getFullURL(), PROTO_CURRENT );
 478                         $vals['descriptionurl'] = wfExpandUrl( $file->getDescriptionUrl(), PROTO_CURRENT );
 479                 }
 480
 481                 if ( $sha1 ) {
 482                         $vals['sha1'] = wfBaseConvert( $file->getSha1(), 36, 16, 40 );
 483                 }
 484
 485                 if ( $meta ) {
 486                         wfSuppressWarnings();
 487                         $metadata = unserialize( $file->getMetadata() );
 488                         wfRestoreWarnings();
 489                         if ( $metadata && $version !== 'latest' ) {
 490                                 $metadata = $file->convertMetadataVersion( $metadata, $version );
 491                         }
 492                         $vals['metadata'] = $metadata ? self::processMetaData( $metadata, $result ) : null;
 493                 }
 494                 if ( $commonmeta ) {
 495                         $metaArray = $file->getCommonMetaArray();
 496                         $vals['commonmetadata'] = $metaArray ? self::processMetaData( $metaArray, $result ) : array();
 497                 }
 498
 499                 if ( $extmetadata ) {
 500                         // Note, this should return an array where all the keys
 501                         // start with a letter, and all the values are strings.
 502                         // Thus there should be no issue with format=xml.
 503                         $format = new FormatMetadata;
 504                         $format->setSingleLanguage( !$opts['multilang'] );
 505                         $format->getContext()->setLanguage( $opts['language'] );
 506                         $extmetaArray = $format->fetchExtendedMetadata( $file );
 507                         if ( $opts['extmetadatafilter'] ) {
 508                                 $extmetaArray = array_intersect_key(
 509                                         $extmetaArray, array_flip( $opts['extmetadatafilter'] )
 510                                 );
 511                         }
 512                         $vals['extmetadata'] = $extmetaArray;
 513                 }
 514
 515                 if ( $mime ) {
 516                         $vals['mime'] = $file->getMimeType();
 517                 }
 518
 519                 if ( $mediatype ) {
 520                         $vals['mediatype'] = $file->getMediaType();
 521                 }
 522
 523                 if ( $archive && $file->isOld() ) {
 524                         $vals['archivename'] = $file->getArchiveName();
 525                 }
 526
 527                 if ( $bitdepth ) {
 528                         $vals['bitdepth'] = $file->getBitDepth();
 529                 }
 530
 531                 return $vals;
 532         }
 533
 534         /**
 535          * Get the count of image transformations performed
 536          *
 537          * If this is >= TRANSFORM_LIMIT, you should probably stop processing images.
 538          *
 539          * @return integer count
 540          */
 541         static function getTransformCount() {
 542                 return self::$transformCount;
 543         }
 544
 545         /**
 546          *
 547          * @param $metadata Array
 548          * @param $result ApiResult
 549          * @return Array
 550          */
 551         public static function processMetaData( $metadata, $result ) {
 552                 $retval = array();
 553                 if ( is_array( $metadata ) ) {
 554                         foreach ( $metadata as $key => $value ) {
 555                                 $r = array( 'name' => $key );
 556                                 if ( is_array( $value ) ) {
 557                                         $r['value'] = self::processMetaData( $value, $result );
 558                                 } else {
 559                                         $r['value'] = $value;
 560                                 }
 561                                 $retval[] = $r;
 562                         }
 563                 }
 564                 $result->setIndexedTagName( $retval, 'metadata' );
 565
 566                 return $retval;
 567         }
 568
 569         public function getCacheMode( $params ) {
 570                 if ( $this->userCanSeeRevDel() ) {
 571                         return 'private';
 572                 }
 573
 574                 return 'public';
 575         }
 576
 577         /**
 578          * @param $img File
 579          * @param null|string $start
 580          * @return string
 581          */
 582         protected function getContinueStr( $img, $start = null ) {
 583                 if ( $start === null ) {
 584                         $start = $img->getTimestamp();
 585                 }
 586
 587                 return $img->getOriginalTitle()->getDBkey() . '|' . $start;
 588         }
 589
 590         public function getAllowedParams() {
 591                 global $wgContLang;
 592
 593                 return array(
 594                         'prop' => array(
 595                                 ApiBase::PARAM_ISMULTI => true,
 596                                 ApiBase::PARAM_DFLT => 'timestamp|user',
 597                                 ApiBase::PARAM_TYPE => self::getPropertyNames()
 598                         ),
 599                         'limit' => array(
 600                                 ApiBase::PARAM_TYPE => 'limit',
 601                                 ApiBase::PARAM_DFLT => 1,
 602                                 ApiBase::PARAM_MIN => 1,
 603                                 ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
 604                                 ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2
 605                         ),
 606                         'start' => array(
 607                                 ApiBase::PARAM_TYPE => 'timestamp'
 608                         ),
 609                         'end' => array(
 610                                 ApiBase::PARAM_TYPE => 'timestamp'
 611                         ),
 612                         'urlwidth' => array(
 613                                 ApiBase::PARAM_TYPE => 'integer',
 614                                 ApiBase::PARAM_DFLT => -1
 615                         ),
 616                         'urlheight' => array(
 617                                 ApiBase::PARAM_TYPE => 'integer',
 618                                 ApiBase::PARAM_DFLT => -1
 619                         ),
 620                         'metadataversion' => array(
 621                                 ApiBase::PARAM_TYPE => 'string',
 622                                 ApiBase::PARAM_DFLT => '1',
 623                         ),
 624                         'extmetadatalanguage' => array(
 625                                 ApiBase::PARAM_TYPE => 'string',
 626                                 ApiBase::PARAM_DFLT => $wgContLang->getCode(),
 627                         ),
 628                         'extmetadatamultilang' => array(
 629                                 ApiBase::PARAM_TYPE => 'boolean',
 630                                 ApiBase::PARAM_DFLT => false,
 631                         ),
 632                         'extmetadatafilter' => array(
 633                                 ApiBase::PARAM_TYPE => 'string',
 634                                 ApiBase::PARAM_ISMULTI => true,
 635                         ),
 636                         'urlparam' => array(
 637                                 ApiBase::PARAM_DFLT => '',
 638                                 ApiBase::PARAM_TYPE => 'string',
 639                         ),
 640                         'continue' => null,
 641                         'localonly' => false,
 642                 );
 643         }
 644
 645         /**
 646          * Returns all possible parameters to iiprop
 647          *
 648          * @param array $filter List of properties to filter out
 649          *
 650          * @return Array
 651          */
 652         public static function getPropertyNames( $filter = array() ) {
 653                 return array_diff( array_keys( self::getProperties() ), $filter );
 654         }
 655
 656         /**
 657          * Returns array key value pairs of properties and their descriptions
 658          *
 659          * @param string $modulePrefix
 660          * @return array
 661          */
 662         private static function getProperties( $modulePrefix = '' ) {
 663                 return array(
 664                         'timestamp' =>      ' timestamp     - Adds timestamp for the uploaded version',
 665                         'user' =>           ' user          - Adds the user who uploaded the image version',
 666                         'userid' =>         ' userid        - Add the user ID that uploaded the image version',
 667                         'comment' =>        ' comment       - Comment on the version',
 668                         'parsedcomment' =>  ' parsedcomment - Parse the comment on the version',
 669                         'canonicaltitle' => ' canonicaltitle - Adds the canonical title of the image file',
 670                         'url' =>            ' url           - Gives URL to the image and the description page',
 671                         'size' =>           ' size          - Adds the size of the image in bytes ' .
 672                                 'and the height, width and page count (if applicable)',
 673                         'dimensions' =>     ' dimensions    - Alias for size', // B/C with Allimages
 674                         'sha1' =>           ' sha1          - Adds SHA-1 hash for the image',
 675                         'mime' =>           ' mime          - Adds MIME type of the image',
 676                         'thumbmime' =>      ' thumbmime     - Adds MIME type of the image thumbnail' .
 677                                 ' (requires url and param ' . $modulePrefix . 'urlwidth)',
 678                         'mediatype' =>      ' mediatype     - Adds the media type of the image',
 679                         'metadata' =>       ' metadata      - Lists Exif metadata for the version of the image',
 680                         'commonmetadata' => ' commonmetadata - Lists file format generic metadata ' .
 681                                 'for the version of the image',
 682                         'extmetadata' =>    ' extmetadata   - Lists formatted metadata combined ' .
 683                                 'from multiple sources. Results are HTML formatted.',
 684                         'archivename' =>    ' archivename   - Adds the file name of the archive ' .
 685                                 'version for non-latest versions',
 686                         'bitdepth' =>       ' bitdepth      - Adds the bit depth of the version',
 687                         'uploadwarning' =>  ' uploadwarning - Used by the Special:Upload page to ' .
 688                                 'get information about an existing file. Not intended for use outside MediaWiki core',
 689                 );
 690         }
 691
 692         /**
 693          * Returns the descriptions for the properties provided by getPropertyNames()
 694          *
 695          * @param array $filter List of properties to filter out
 696          * @param string $modulePrefix
 697          * @return array
 698          */
 699         public static function getPropertyDescriptions( $filter = array(), $modulePrefix = '' ) {
 700                 return array_merge(
 701                         array( 'What image information to get:' ),
 702                         array_values( array_diff_key( self::getProperties( $modulePrefix ), array_flip( $filter ) ) )
 703                 );
 704         }
 705
 706         /**
 707          * Return the API documentation for the parameters.
 708          * @return Array parameter documentation.
 709          */
 710         public function getParamDescription() {
 711                 $p = $this->getModulePrefix();
 712
 713                 return array(
 714                         'prop' => self::getPropertyDescriptions( array(), $p ),
 715                         'urlwidth' => array(
 716                                 "If {$p}prop=url is set, a URL to an image scaled to this width will be returned.",
 717                                 'For performance reasons if this option is used, ' .
 718                                         'no more than ' . self::TRANSFORM_LIMIT . ' scaled images will be returned.'
 719                         ),
 720                         'urlheight' => "Similar to {$p}urlwidth.",
 721                         'urlparam' => array( "A handler specific parameter string. For example, pdf's ",
 722                                 "might use 'page15-100px'. {$p}urlwidth must be used and be consistent with {$p}urlparam" ),
 723                         'limit' => 'How many image revisions to return per image',
 724                         'start' => 'Timestamp to start listing from',
 725                         'end' => 'Timestamp to stop listing at',
 726                         'metadataversion'
 727                                 => array( "Version of metadata to use. if 'latest' is specified, use latest version.",
 728                                 "Defaults to '1' for backwards compatibility" ),
 729                         'extmetadatalanguage' => array(
 730                                 'What language to fetch extmetadata in. This affects both which',
 731                                 'translation to fetch, if multiple are available, as well as how things',
 732                                 'like numbers and various values are formatted.'
 733                         ),
 734                         'extmetadatamultilang'
 735                                 =>'If translations for extmetadata property are available, fetch all of them.',
 736                         'extmetadatafilter'
 737                                 => "If specified and non-empty, only these keys will be returned for {$p}prop=extmetadata",
 738                         'continue' => 'If the query response includes a continue value, ' .
 739                                 'use it here to get another page of results',
 740                         'localonly' => 'Look only for files in the local repository',
 741                 );
 742         }
 743
 744         public static function getResultPropertiesFiltered( $filter = array() ) {
 745                 $props = array(
 746                         'timestamp' => array(
 747                                 'timestamp' => 'timestamp'
 748                         ),
 749                         'user' => array(
 750                                 'userhidden' => 'boolean',
 751                                 'user' => 'string',
 752                                 'anon' => 'boolean'
 753                         ),
 754                         'userid' => array(
 755                                 'userhidden' => 'boolean',
 756                                 'userid' => 'integer',
 757                                 'anon' => 'boolean'
 758                         ),
 759                         'size' => array(
 760                                 'size' => 'integer',
 761                                 'width' => 'integer',
 762                                 'height' => 'integer',
 763                                 'pagecount' => array(
 764                                         ApiBase::PROP_TYPE => 'integer',
 765                                         ApiBase::PROP_NULLABLE => true
 766                                 )
 767                         ),
 768                         'dimensions' => array(
 769                                 'size' => 'integer',
 770                                 'width' => 'integer',
 771                                 'height' => 'integer',
 772                                 'pagecount' => array(
 773                                         ApiBase::PROP_TYPE => 'integer',
 774                                         ApiBase::PROP_NULLABLE => true
 775                                 )
 776                         ),
 777                         'comment' => array(
 778                                 'commenthidden' => 'boolean',
 779                                 'comment' => array(
 780                                         ApiBase::PROP_TYPE => 'string',
 781                                         ApiBase::PROP_NULLABLE => true
 782                                 )
 783                         ),
 784                         'parsedcomment' => array(
 785                                 'commenthidden' => 'boolean',
 786                                 'parsedcomment' => array(
 787                                         ApiBase::PROP_TYPE => 'string',
 788                                         ApiBase::PROP_NULLABLE => true
 789                                 )
 790                         ),
 791                         'canonicaltitle' => array(
 792                                 'canonicaltitle' => array(
 793                                         ApiBase::PROP_TYPE => 'string',
 794                                         ApiBase::PROP_NULLABLE => true
 795                                 )
 796                         ),
 797                         'url' => array(
 798                                 'filehidden' => 'boolean',
 799                                 'thumburl' => array(
 800                                         ApiBase::PROP_TYPE => 'string',
 801                                         ApiBase::PROP_NULLABLE => true
 802                                 ),
 803                                 'thumbwidth' => array(
 804                                         ApiBase::PROP_TYPE => 'integer',
 805                                         ApiBase::PROP_NULLABLE => true
 806                                 ),
 807                                 'thumbheight' => array(
 808                                         ApiBase::PROP_TYPE => 'integer',
 809                                         ApiBase::PROP_NULLABLE => true
 810                                 ),
 811                                 'thumberror' => array(
 812                                         ApiBase::PROP_TYPE => 'string',
 813                                         ApiBase::PROP_NULLABLE => true
 814                                 ),
 815                                 'url' => array(
 816                                         ApiBase::PROP_TYPE => 'string',
 817                                         ApiBase::PROP_NULLABLE => true
 818                                 ),
 819                                 'descriptionurl' => array(
 820                                         ApiBase::PROP_TYPE => 'string',
 821                                         ApiBase::PROP_NULLABLE => true
 822                                 )
 823                         ),
 824                         'sha1' => array(
 825                                 'filehidden' => 'boolean',
 826                                 'sha1' => array(
 827                                         ApiBase::PROP_TYPE => 'string',
 828                                         ApiBase::PROP_NULLABLE => true
 829                                 )
 830                         ),
 831                         'mime' => array(
 832                                 'filehidden' => 'boolean',
 833                                 'mime' => array(
 834                                         ApiBase::PROP_TYPE => 'string',
 835                                         ApiBase::PROP_NULLABLE => true
 836                                 )
 837                         ),
 838                         'thumbmime' => array(
 839                                 'filehidden' => 'boolean',
 840                                 'thumbmime' => array(
 841                                         ApiBase::PROP_TYPE => 'string',
 842                                         ApiBase::PROP_NULLABLE => true
 843                                 )
 844                         ),
 845                         'mediatype' => array(
 846                                 'filehidden' => 'boolean',
 847                                 'mediatype' => array(
 848                                         ApiBase::PROP_TYPE => 'string',
 849                                         ApiBase::PROP_NULLABLE => true
 850                                 )
 851                         ),
 852                         'archivename' => array(
 853                                 'filehidden' => 'boolean',
 854                                 'archivename' => array(
 855                                         ApiBase::PROP_TYPE => 'string',
 856                                         ApiBase::PROP_NULLABLE => true
 857                                 )
 858                         ),
 859                         'bitdepth' => array(
 860                                 'filehidden' => 'boolean',
 861                                 'bitdepth' => array(
 862                                         ApiBase::PROP_TYPE => 'integer',
 863                                         ApiBase::PROP_NULLABLE => true
 864                                 )
 865                         ),
 866                 );
 867
 868                 return array_diff_key( $props, array_flip( $filter ) );
 869         }
 870
 871         public function getResultProperties() {
 872                 return self::getResultPropertiesFiltered();
 873         }
 874
 875         public function getDescription() {
 876                 return 'Returns image information and upload history.';
 877         }
 878
 879         public function getPossibleErrors() {
 880                 $p = $this->getModulePrefix();
 881
 882                 return array_merge( parent::getPossibleErrors(), array(
 883                         array( 'code' => "{$p}urlwidth", 'info' => "{$p}urlheight cannot be used without {$p}urlwidth" ),
 884                         array( 'code' => 'urlparam', 'info' => "Invalid value for {$p}urlparam" ),
 885                         array( 'code' => 'urlparam_no_width', 'info' => "{$p}urlparam requires {$p}urlwidth" ),
 886                 ) );
 887         }
 888
 889         public function getExamples() {
 890                 return array(
 891                         'api.php?action=query&titles=File:Albert%20Einstein%20Head.jpg&prop=imageinfo',
 892                         'api.php?action=query&titles=File:Test.jpg&prop=imageinfo&iilimit=50&' .
 893                                 'iiend=20071231235959&iiprop=timestamp|user|url',
 894                 );
 895         }
 896
 897         public function getHelpUrls() {
 898                 return 'https://www.mediawiki.org/wiki/API:Properties#imageinfo_.2F_ii';
 899         }
 900 }