[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Media-handling base classes and generic functionality.
   4   *
   5   * This program is free software; you can redistribute it and/or modify
   6   * it under the terms of the GNU General Public License as published by
   7   * the Free Software Foundation; either version 2 of the License, or
   8   * (at your option) any later version.
   9   *
  10   * This program is distributed in the hope that it will be useful,
  11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13   * GNU General Public License for more details.
  14   *
  15   * You should have received a copy of the GNU General Public License along
  16   * with this program; if not, write to the Free Software Foundation, Inc.,
  17   * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18   * http://www.gnu.org/copyleft/gpl.html
  19   *
  20   * @file
  21   * @ingroup Media
  22   */
  23  
  24  /**
  25   * Base media handler class
  26   *
  27   * @ingroup Media
  28   */
  29  abstract class MediaHandler {
  30      const TRANSFORM_LATER = 1;
  31      const METADATA_GOOD = true;
  32      const METADATA_BAD = false;
  33      const METADATA_COMPATIBLE = 2; // for old but backwards compatible.
  34      /**
  35       * Max length of error logged by logErrorForExternalProcess()
  36       */
  37      const MAX_ERR_LOG_SIZE = 65535;
  38  
  39      /** @var MediaHandler[] Instance cache with array of MediaHandler */
  40      protected static $handlers = array();
  41  
  42      /**
  43       * Get a MediaHandler for a given MIME type from the instance cache
  44       *
  45       * @param string $type
  46       * @return MediaHandler
  47       */
  48  	static function getHandler( $type ) {
  49          global $wgMediaHandlers;
  50          if ( !isset( $wgMediaHandlers[$type] ) ) {
  51              wfDebug( __METHOD__ . ": no handler found for $type.\n" );
  52  
  53              return false;
  54          }
  55          $class = $wgMediaHandlers[$type];
  56          if ( !isset( self::$handlers[$class] ) ) {
  57              self::$handlers[$class] = new $class;
  58              if ( !self::$handlers[$class]->isEnabled() ) {
  59                  wfDebug( __METHOD__ . ": $class is not enabled\n" );
  60                  self::$handlers[$class] = false;
  61              }
  62          }
  63  
  64          return self::$handlers[$class];
  65      }
  66  
  67      /**
  68       * Resets all static caches
  69       */
  70  	public static function resetCache() {
  71          self::$handlers = array();
  72      }
  73  
  74      /**
  75       * Get an associative array mapping magic word IDs to parameter names.
  76       * Will be used by the parser to identify parameters.
  77       */
  78      abstract function getParamMap();
  79  
  80      /**
  81       * Validate a thumbnail parameter at parse time.
  82       * Return true to accept the parameter, and false to reject it.
  83       * If you return false, the parser will do something quiet and forgiving.
  84       *
  85       * @param string $name
  86       * @param mixed $value
  87       */
  88      abstract function validateParam( $name, $value );
  89  
  90      /**
  91       * Merge a parameter array into a string appropriate for inclusion in filenames
  92       *
  93       * @param array $params Array of parameters that have been through normaliseParams.
  94       * @return string
  95       */
  96      abstract function makeParamString( $params );
  97  
  98      /**
  99       * Parse a param string made with makeParamString back into an array
 100       *
 101       * @param string $str The parameter string without file name (e.g. 122px)
 102       * @return array|bool Array of parameters or false on failure.
 103       */
 104      abstract function parseParamString( $str );
 105  
 106      /**
 107       * Changes the parameter array as necessary, ready for transformation.
 108       * Should be idempotent.
 109       * Returns false if the parameters are unacceptable and the transform should fail
 110       * @param File $image
 111       * @param array $params
 112       */
 113      abstract function normaliseParams( $image, &$params );
 114  
 115      /**
 116       * Get an image size array like that returned by getimagesize(), or false if it
 117       * can't be determined.
 118       *
 119       * This function is used for determining the width, height and bitdepth directly
 120       * from an image. The results are stored in the database in the img_width,
 121       * img_height, img_bits fields.
 122       *
 123       * @note If this is a multipage file, return the width and height of the
 124       *  first page.
 125       *
 126       * @param File $image The image object, or false if there isn't one
 127       * @param string $path The filename
 128       * @return array Follow the format of PHP getimagesize() internal function.
 129       *   See http://www.php.net/getimagesize. MediaWiki will only ever use the
 130       *   first two array keys (the width and height), and the 'bits' associative
 131       *   key. All other array keys are ignored. Returning a 'bits' key is optional
 132       *   as not all formats have a notion of "bitdepth".
 133       */
 134      abstract function getImageSize( $image, $path );
 135  
 136      /**
 137       * Get handler-specific metadata which will be saved in the img_metadata field.
 138       *
 139       * @param File $image The image object, or false if there isn't one.
 140       *   Warning, FSFile::getPropsFromPath might pass an (object)array() instead (!)
 141       * @param string $path The filename
 142       * @return string A string of metadata in php serialized form (Run through serialize())
 143       */
 144  	function getMetadata( $image, $path ) {
 145          return '';
 146      }
 147  
 148      /**
 149       * Get metadata version.
 150       *
 151       * This is not used for validating metadata, this is used for the api when returning
 152       * metadata, since api content formats should stay the same over time, and so things
 153       * using ForeignApiRepo can keep backwards compatibility
 154       *
 155       * All core media handlers share a common version number, and extensions can
 156       * use the GetMetadataVersion hook to append to the array (they should append a unique
 157       * string so not to get confusing). If there was a media handler named 'foo' with metadata
 158       * version 3 it might add to the end of the array the element 'foo=3'. if the core metadata
 159       * version is 2, the end version string would look like '2;foo=3'.
 160       *
 161       * @return string Version string
 162       */
 163  	static function getMetadataVersion() {
 164          $version = array( '2' ); // core metadata version
 165          wfRunHooks( 'GetMetadataVersion', array( &$version ) );
 166  
 167          return implode( ';', $version );
 168      }
 169  
 170      /**
 171       * Convert metadata version.
 172       *
 173       * By default just returns $metadata, but can be used to allow
 174       * media handlers to convert between metadata versions.
 175       *
 176       * @param string|array $metadata Metadata array (serialized if string)
 177       * @param int $version Target version
 178       * @return array Serialized metadata in specified version, or $metadata on fail.
 179       */
 180  	function convertMetadataVersion( $metadata, $version = 1 ) {
 181          if ( !is_array( $metadata ) ) {
 182  
 183              //unserialize to keep return parameter consistent.
 184              wfSuppressWarnings();
 185              $ret = unserialize( $metadata );
 186              wfRestoreWarnings();
 187  
 188              return $ret;
 189          }
 190  
 191          return $metadata;
 192      }
 193  
 194      /**
 195       * Get a string describing the type of metadata, for display purposes.
 196       *
 197       * @note This method is currently unused.
 198       * @param File $image
 199       * @return string
 200       */
 201  	function getMetadataType( $image ) {
 202          return false;
 203      }
 204  
 205      /**
 206       * Check if the metadata string is valid for this handler.
 207       * If it returns MediaHandler::METADATA_BAD (or false), Image
 208       * will reload the metadata from the file and update the database.
 209       * MediaHandler::METADATA_GOOD for if the metadata is a-ok,
 210       * MediaHandler::METADATA_COMPATIBLE if metadata is old but backwards
 211       * compatible (which may or may not trigger a metadata reload).
 212       *
 213       * @note Returning self::METADATA_BAD will trigger a metadata reload from
 214       *  file on page view. Always returning this from a broken file, or suddenly
 215       *  triggering as bad metadata for a large number of files can cause
 216       *  performance problems.
 217       * @param File $image
 218       * @param string $metadata The metadata in serialized form
 219       * @return bool
 220       */
 221  	function isMetadataValid( $image, $metadata ) {
 222          return self::METADATA_GOOD;
 223      }
 224  
 225      /**
 226       * Get an array of standard (FormatMetadata type) metadata values.
 227       *
 228       * The returned data is largely the same as that from getMetadata(),
 229       * but formatted in a standard, stable, handler-independent way.
 230       * The idea being that some values like ImageDescription or Artist
 231       * are universal and should be retrievable in a handler generic way.
 232       *
 233       * The specific properties are the type of properties that can be
 234       * handled by the FormatMetadata class. These values are exposed to the
 235       * user via the filemetadata parser function.
 236       *
 237       * Details of the response format of this function can be found at
 238       * https://www.mediawiki.org/wiki/Manual:File_metadata_handling
 239       * tl/dr: the response is an associative array of
 240       * properties keyed by name, but the value can be complex. You probably
 241       * want to call one of the FormatMetadata::flatten* functions on the
 242       * property values before using them, or call
 243       * FormatMetadata::getFormattedData() on the full response array, which
 244       * transforms all values into prettified, human-readable text.
 245       *
 246       * Subclasses overriding this function must return a value which is a
 247       * valid API response fragment (all associative array keys are valid
 248       * XML tagnames).
 249       *
 250       * Note, if the file simply has no metadata, but the handler supports
 251       * this interface, it should return an empty array, not false.
 252       *
 253       * @param File $file
 254       * @return array|bool False if interface not supported
 255       * @since 1.23
 256       */
 257  	public function getCommonMetaArray( File $file ) {
 258          return false;
 259      }
 260  
 261      /**
 262       * Get a MediaTransformOutput object representing an alternate of the transformed
 263       * output which will call an intermediary thumbnail assist script.
 264       *
 265       * Used when the repository has a thumbnailScriptUrl option configured.
 266       *
 267       * Return false to fall back to the regular getTransform().
 268       * @param File $image
 269       * @param string $script
 270       * @param array $params
 271       * @return bool|ThumbnailImage
 272       */
 273  	function getScriptedTransform( $image, $script, $params ) {
 274          return false;
 275      }
 276  
 277      /**
 278       * Get a MediaTransformOutput object representing the transformed output. Does not
 279       * actually do the transform.
 280       *
 281       * @param File $image The image object
 282       * @param string $dstPath Filesystem destination path
 283       * @param string $dstUrl Destination URL to use in output HTML
 284       * @param array $params Arbitrary set of parameters validated by $this->validateParam()
 285       * @return MediaTransformOutput
 286       */
 287  	final function getTransform( $image, $dstPath, $dstUrl, $params ) {
 288          return $this->doTransform( $image, $dstPath, $dstUrl, $params, self::TRANSFORM_LATER );
 289      }
 290  
 291      /**
 292       * Get a MediaTransformOutput object representing the transformed output. Does the
 293       * transform unless $flags contains self::TRANSFORM_LATER.
 294       *
 295       * @param File $image The image object
 296       * @param string $dstPath Filesystem destination path
 297       * @param string $dstUrl Destination URL to use in output HTML
 298       * @param array $params Arbitrary set of parameters validated by $this->validateParam()
 299       *   Note: These parameters have *not* gone through $this->normaliseParams()
 300       * @param int $flags A bitfield, may contain self::TRANSFORM_LATER
 301       * @return MediaTransformOutput
 302       */
 303      abstract function doTransform( $image, $dstPath, $dstUrl, $params, $flags = 0 );
 304  
 305      /**
 306       * Get the thumbnail extension and MIME type for a given source MIME type
 307       *
 308       * @param string $ext Extension of original file
 309       * @param string $mime MIME type of original file
 310       * @param array $params Handler specific rendering parameters
 311       * @return array Thumbnail extension and MIME type
 312       */
 313  	function getThumbType( $ext, $mime, $params = null ) {
 314          $magic = MimeMagic::singleton();
 315          if ( !$ext || $magic->isMatchingExtension( $ext, $mime ) === false ) {
 316              // The extension is not valid for this MIME type and we do
 317              // recognize the MIME type
 318              $extensions = $magic->getExtensionsForType( $mime );
 319              if ( $extensions ) {
 320                  return array( strtok( $extensions, ' ' ), $mime );
 321              }
 322          }
 323  
 324          // The extension is correct (true) or the MIME type is unknown to
 325          // MediaWiki (null)
 326          return array( $ext, $mime );
 327      }
 328  
 329      /**
 330       * Get useful response headers for GET/HEAD requests for a file with the given metadata
 331       *
 332       * @param mixed $metadata Result of the getMetadata() function of this handler for a file
 333       * @return array
 334       */
 335  	public function getStreamHeaders( $metadata ) {
 336          return array();
 337      }
 338  
 339      /**
 340       * True if the handled types can be transformed
 341       *
 342       * @param File $file
 343       * @return bool
 344       */
 345  	function canRender( $file ) {
 346          return true;
 347      }
 348  
 349      /**
 350       * True if handled types cannot be displayed directly in a browser
 351       * but can be rendered
 352       *
 353       * @param File $file
 354       * @return bool
 355       */
 356  	function mustRender( $file ) {
 357          return false;
 358      }
 359  
 360      /**
 361       * True if the type has multi-page capabilities
 362       *
 363       * @param File $file
 364       * @return bool
 365       */
 366  	function isMultiPage( $file ) {
 367          return false;
 368      }
 369  
 370      /**
 371       * Page count for a multi-page document, false if unsupported or unknown
 372       *
 373       * @param File $file
 374       * @return bool
 375       */
 376  	function pageCount( $file ) {
 377          return false;
 378      }
 379  
 380      /**
 381       * The material is vectorized and thus scaling is lossless
 382       *
 383       * @param File $file
 384       * @return bool
 385       */
 386  	function isVectorized( $file ) {
 387          return false;
 388      }
 389  
 390      /**
 391       * The material is an image, and is animated.
 392       * In particular, video material need not return true.
 393       * @note Before 1.20, this was a method of ImageHandler only
 394       *
 395       * @param File $file
 396       * @return bool
 397       */
 398  	function isAnimatedImage( $file ) {
 399          return false;
 400      }
 401  
 402      /**
 403       * If the material is animated, we can animate the thumbnail
 404       * @since 1.20
 405       *
 406       * @param File $file
 407       * @return bool If material is not animated, handler may return any value.
 408       */
 409  	function canAnimateThumbnail( $file ) {
 410          return true;
 411      }
 412  
 413      /**
 414       * False if the handler is disabled for all files
 415       * @return bool
 416       */
 417  	function isEnabled() {
 418          return true;
 419      }
 420  
 421      /**
 422       * Get an associative array of page dimensions
 423       * Currently "width" and "height" are understood, but this might be
 424       * expanded in the future.
 425       * Returns false if unknown.
 426       *
 427       * It is expected that handlers for paged media (e.g. DjVuHandler)
 428       * will override this method so that it gives the correct results
 429       * for each specific page of the file, using the $page argument.
 430       *
 431       * @note For non-paged media, use getImageSize.
 432       *
 433       * @param File $image
 434       * @param int $page What page to get dimensions of
 435       * @return array|bool
 436       */
 437  	function getPageDimensions( $image, $page ) {
 438          $gis = $this->getImageSize( $image, $image->getLocalRefPath() );
 439          if ( $gis ) {
 440              return array(
 441                  'width' => $gis[0],
 442                  'height' => $gis[1]
 443              );
 444          } else {
 445              return false;
 446          }
 447      }
 448  
 449      /**
 450       * Generic getter for text layer.
 451       * Currently overloaded by PDF and DjVu handlers
 452       * @param File $image
 453       * @param int $page Page number to get information for
 454       * @return bool|string Page text or false when no text found or if
 455       *   unsupported.
 456       */
 457  	function getPageText( $image, $page ) {
 458          return false;
 459      }
 460  
 461      /**
 462       * Get the text of the entire document.
 463       * @param File $file
 464       * @return bool|string The text of the document or false if unsupported.
 465       */
 466  	public function getEntireText( File $file ) {
 467          $numPages = $file->pageCount();
 468          if ( !$numPages ) {
 469              // Not a multipage document
 470              return $this->getPageText( $file, 1 );
 471          }
 472          $document = '';
 473          for ( $i = 1; $i <= $numPages; $i++ ) {
 474              $curPage = $this->getPageText( $file, $i );
 475              if ( is_string( $curPage ) ) {
 476                  $document .= $curPage . "\n";
 477              }
 478          }
 479          if ( $document !== '' ) {
 480              return $document;
 481          }
 482          return false;
 483      }
 484  
 485      /**
 486       * Get an array structure that looks like this:
 487       *
 488       * array(
 489       *    'visible' => array(
 490       *       'Human-readable name' => 'Human readable value',
 491       *       ...
 492       *    ),
 493       *    'collapsed' => array(
 494       *       'Human-readable name' => 'Human readable value',
 495       *       ...
 496       *    )
 497       * )
 498       * The UI will format this into a table where the visible fields are always
 499       * visible, and the collapsed fields are optionally visible.
 500       *
 501       * The function should return false if there is no metadata to display.
 502       */
 503  
 504      /**
 505       * @todo FIXME: This interface is not very flexible. The media handler
 506       * should generate HTML instead. It can do all the formatting according
 507       * to some standard. That makes it possible to do things like visual
 508       * indication of grouped and chained streams in ogg container files.
 509       * @param File $image
 510       * @return array|bool
 511       */
 512  	function formatMetadata( $image ) {
 513          return false;
 514      }
 515  
 516      /** sorts the visible/invisible field.
 517       * Split off from ImageHandler::formatMetadata, as used by more than
 518       * one type of handler.
 519       *
 520       * This is used by the media handlers that use the FormatMetadata class
 521       *
 522       * @param array $metadataArray Metadata array
 523       * @return array Array for use displaying metadata.
 524       */
 525  	function formatMetadataHelper( $metadataArray ) {
 526          $result = array(
 527              'visible' => array(),
 528              'collapsed' => array()
 529          );
 530  
 531          $formatted = FormatMetadata::getFormattedData( $metadataArray );
 532          // Sort fields into visible and collapsed
 533          $visibleFields = $this->visibleMetadataFields();
 534          foreach ( $formatted as $name => $value ) {
 535              $tag = strtolower( $name );
 536              self::addMeta( $result,
 537                  in_array( $tag, $visibleFields ) ? 'visible' : 'collapsed',
 538                  'exif',
 539                  $tag,
 540                  $value
 541              );
 542          }
 543  
 544          return $result;
 545      }
 546  
 547      /**
 548       * Get a list of metadata items which should be displayed when
 549       * the metadata table is collapsed.
 550       *
 551       * @return array Array of strings
 552       */
 553  	protected function visibleMetadataFields() {
 554          return FormatMetadata::getVisibleFields();
 555      }
 556  
 557      /**
 558       * This is used to generate an array element for each metadata value
 559       * That array is then used to generate the table of metadata values
 560       * on the image page
 561       *
 562       * @param array &$array An array containing elements for each type of visibility
 563       *   and each of those elements being an array of metadata items. This function adds
 564       *   a value to that array.
 565       * @param string $visibility ('visible' or 'collapsed') if this value is hidden
 566       *   by default.
 567       * @param string $type Type of metadata tag (currently always 'exif')
 568       * @param string $id The name of the metadata tag (like 'artist' for example).
 569       *   its name in the table displayed is the message "$type-$id" (Ex exif-artist ).
 570       * @param string $value Thingy goes into a wikitext table; it used to be escaped but
 571       *   that was incompatible with previous practise of customized display
 572       *   with wikitext formatting via messages such as 'exif-model-value'.
 573       *   So the escaping is taken back out, but generally this seems a confusing
 574       *   interface.
 575       * @param bool|string $param Value to pass to the message for the name of the field
 576       *   as $1. Currently this parameter doesn't seem to ever be used.
 577       *
 578       * Note, everything here is passed through the parser later on (!)
 579       */
 580  	protected static function addMeta( &$array, $visibility, $type, $id, $value, $param = false ) {
 581          $msg = wfMessage( "$type-$id", $param );
 582          if ( $msg->exists() ) {
 583              $name = $msg->text();
 584          } else {
 585              // This is for future compatibility when using instant commons.
 586              // So as to not display as ugly a name if a new metadata
 587              // property is defined that we don't know about
 588              // (not a major issue since such a property would be collapsed
 589              // by default).
 590              wfDebug( __METHOD__ . ' Unknown metadata name: ' . $id . "\n" );
 591              $name = wfEscapeWikiText( $id );
 592          }
 593          $array[$visibility][] = array(
 594              'id' => "$type-$id",
 595              'name' => $name,
 596              'value' => $value
 597          );
 598      }
 599  
 600      /**
 601       * Short description. Shown on Special:Search results.
 602       *
 603       * @param File $file
 604       * @return string
 605       */
 606  	function getShortDesc( $file ) {
 607          return self::getGeneralShortDesc( $file );
 608      }
 609  
 610      /**
 611       * Long description. Shown under image on image description page surounded by ().
 612       *
 613       * @param File $file
 614       * @return string
 615       */
 616  	function getLongDesc( $file ) {
 617          return self::getGeneralLongDesc( $file );
 618      }
 619  
 620      /**
 621       * Used instead of getShortDesc if there is no handler registered for file.
 622       *
 623       * @param File $file
 624       * @return string
 625       */
 626  	static function getGeneralShortDesc( $file ) {
 627          global $wgLang;
 628  
 629          return htmlspecialchars( $wgLang->formatSize( $file->getSize() ) );
 630      }
 631  
 632      /**
 633       * Used instead of getLongDesc if there is no handler registered for file.
 634       *
 635       * @param File $file
 636       * @return string
 637       */
 638  	static function getGeneralLongDesc( $file ) {
 639          return wfMessage( 'file-info' )->sizeParams( $file->getSize() )
 640              ->params( $file->getMimeType() )->parse();
 641      }
 642  
 643      /**
 644       * Calculate the largest thumbnail width for a given original file size
 645       * such that the thumbnail's height is at most $maxHeight.
 646       * @param int $boxWidth Width of the thumbnail box.
 647       * @param int $boxHeight Height of the thumbnail box.
 648       * @param int $maxHeight Maximum height expected for the thumbnail.
 649       * @return int
 650       */
 651  	public static function fitBoxWidth( $boxWidth, $boxHeight, $maxHeight ) {
 652          $idealWidth = $boxWidth * $maxHeight / $boxHeight;
 653          $roundedUp = ceil( $idealWidth );
 654          if ( round( $roundedUp * $boxHeight / $boxWidth ) > $maxHeight ) {
 655              return floor( $idealWidth );
 656          } else {
 657              return $roundedUp;
 658          }
 659      }
 660  
 661      /**
 662       * Shown in file history box on image description page.
 663       *
 664       * @param File $file
 665       * @return string Dimensions
 666       */
 667  	function getDimensionsString( $file ) {
 668          return '';
 669      }
 670  
 671      /**
 672       * Modify the parser object post-transform.
 673       *
 674       * This is often used to do $parser->addOutputHook(),
 675       * in order to add some javascript to render a viewer.
 676       * See TimedMediaHandler or OggHandler for an example.
 677       *
 678       * @param Parser $parser
 679       * @param File $file
 680       */
 681  	function parserTransformHook( $parser, $file ) {
 682      }
 683  
 684      /**
 685       * File validation hook called on upload.
 686       *
 687       * If the file at the given local path is not valid, or its MIME type does not
 688       * match the handler class, a Status object should be returned containing
 689       * relevant errors.
 690       *
 691       * @param string $fileName The local path to the file.
 692       * @return Status
 693       */
 694  	function verifyUpload( $fileName ) {
 695          return Status::newGood();
 696      }
 697  
 698      /**
 699       * Check for zero-sized thumbnails. These can be generated when
 700       * no disk space is available or some other error occurs
 701       *
 702       * @param string $dstPath The location of the suspect file
 703       * @param int $retval Return value of some shell process, file will be deleted if this is non-zero
 704       * @return bool True if removed, false otherwise
 705       */
 706  	function removeBadFile( $dstPath, $retval = 0 ) {
 707          if ( file_exists( $dstPath ) ) {
 708              $thumbstat = stat( $dstPath );
 709              if ( $thumbstat['size'] == 0 || $retval != 0 ) {
 710                  $result = unlink( $dstPath );
 711  
 712                  if ( $result ) {
 713                      wfDebugLog( 'thumbnail',
 714                          sprintf( 'Removing bad %d-byte thumbnail "%s". unlink() succeeded',
 715                              $thumbstat['size'], $dstPath ) );
 716                  } else {
 717                      wfDebugLog( 'thumbnail',
 718                          sprintf( 'Removing bad %d-byte thumbnail "%s". unlink() failed',
 719                              $thumbstat['size'], $dstPath ) );
 720                  }
 721  
 722                  return true;
 723              }
 724          }
 725  
 726          return false;
 727      }
 728  
 729      /**
 730       * Remove files from the purge list.
 731       *
 732       * This is used by some video handlers to prevent ?action=purge
 733       * from removing a transcoded video, which is expensive to
 734       * regenerate.
 735       *
 736       * @see LocalFile::purgeThumbnails
 737       *
 738       * @param array $files
 739       * @param array $options Purge options. Currently will always be
 740       *  an array with a single key 'forThumbRefresh' set to true.
 741       */
 742  	public function filterThumbnailPurgeList( &$files, $options ) {
 743          // Do nothing
 744      }
 745  
 746      /**
 747       * True if the handler can rotate the media
 748       * @since 1.24 non-static. From 1.21-1.23 was static
 749       * @return bool
 750       */
 751  	public function canRotate() {
 752          return false;
 753      }
 754  
 755      /**
 756       * On supporting image formats, try to read out the low-level orientation
 757       * of the file and return the angle that the file needs to be rotated to
 758       * be viewed.
 759       *
 760       * This information is only useful when manipulating the original file;
 761       * the width and height we normally work with is logical, and will match
 762       * any produced output views.
 763       *
 764       * For files we don't know, we return 0.
 765       *
 766       * @param File $file
 767       * @return int 0, 90, 180 or 270
 768       */
 769  	public function getRotation( $file ) {
 770          return 0;
 771      }
 772  
 773      /**
 774       * Log an error that occurred in an external process
 775       *
 776       * Moved from BitmapHandler to MediaHandler with MediaWiki 1.23
 777       *
 778       * @since 1.23
 779       * @param int $retval
 780       * @param string $err Error reported by command. Anything longer than
 781       * MediaHandler::MAX_ERR_LOG_SIZE is stripped off.
 782       * @param string $cmd
 783       */
 784  	protected function logErrorForExternalProcess( $retval, $err, $cmd ) {
 785          # Keep error output limited (bug 57985)
 786          $errMessage = trim( substr( $err, 0, self::MAX_ERR_LOG_SIZE ) );
 787  
 788          wfDebugLog( 'thumbnail',
 789              sprintf( 'thumbnail failed on %s: error %d "%s" from "%s"',
 790                      wfHostname(), $retval, $errMessage, $cmd ) );
 791      }
 792  
 793      /**
 794       * Get list of languages file can be viewed in.
 795       *
 796       * @param File $file
 797       * @return string[] Array of language codes, or empty array if unsupported.
 798       * @since 1.23
 799       */
 800  	public function getAvailableLanguages( File $file ) {
 801          return array();
 802      }
 803  
 804      /**
 805       * On file types that support renderings in multiple languages,
 806       * which language is used by default if unspecified.
 807       *
 808       * If getAvailableLanguages returns a non-empty array, this must return
 809       * a valid language code. Otherwise can return null if files of this
 810       * type do not support alternative language renderings.
 811       *
 812       * @param File $file
 813       * @return string|null Language code or null if multi-language not supported for filetype.
 814       * @since 1.23
 815       */
 816  	public function getDefaultRenderLanguage( File $file ) {
 817          return null;
 818      }
 819  
 820      /**
 821       * If its an audio file, return the length of the file. Otherwise 0.
 822       *
 823       * File::getLength() existed for a long time, but was calling a method
 824       * that only existed in some subclasses of this class (The TMH ones).
 825       *
 826       * @param File $file
 827       * @return float Length in seconds
 828       * @since 1.23
 829       */
 830  	public function getLength( $file ) {
 831          return 0.0;
 832      }
 833  
 834      /**
 835       * True if creating thumbnails from the file is large or otherwise resource-intensive.
 836       * @param File $file
 837       * @return bool
 838       */
 839  	public function isExpensiveToThumbnail( $file ) {
 840          return false;
 841      }
 842  
 843      /**
 844       * Returns whether or not this handler supports the chained generation of thumbnails according
 845       * to buckets
 846       * @return bool
 847       * @since 1.24
 848       */
 849  	public function supportsBucketing() {
 850          return false;
 851      }
 852  
 853      /**
 854       * Returns a normalised params array for which parameters have been cleaned up for bucketing
 855       * purposes
 856       * @param array $params
 857       * @return array
 858       */
 859  	public function sanitizeParamsForBucketing( $params ) {
 860          return $params;
 861      }
 862  }