MediaWiki REL1_34
MediaHandler.php
Go to the documentation of this file.
1<?php
24
30abstract class MediaHandler {
31 const TRANSFORM_LATER = 1;
32 const METADATA_GOOD = true;
33 const METADATA_BAD = false;
34 const METADATA_COMPATIBLE = 2; // for old but backwards compatible.
38 const MAX_ERR_LOG_SIZE = 65535;
39
46 static function getHandler( $type ) {
47 return MediaWikiServices::getInstance()
48 ->getMediaHandlerFactory()->getHandler( $type );
49 }
50
55 abstract public function getParamMap();
56
65 abstract public function validateParam( $name, $value );
66
73 abstract public function makeParamString( $params );
74
81 abstract public function parseParamString( $str );
82
90 abstract public function normaliseParams( $image, &$params );
91
112 abstract function getImageSize( $image, $path );
113
122 public function getMetadata( $image, $path ) {
123 return '';
124 }
125
141 static function getMetadataVersion() {
142 $version = [ '2' ]; // core metadata version
143 Hooks::run( 'GetMetadataVersion', [ &$version ] );
144
145 return implode( ';', $version );
146 }
147
158 function convertMetadataVersion( $metadata, $version = 1 ) {
159 if ( !is_array( $metadata ) ) {
160 // unserialize to keep return parameter consistent.
161 Wikimedia\suppressWarnings();
162 $ret = unserialize( $metadata );
163 Wikimedia\restoreWarnings();
164
165 return $ret;
166 }
167
168 return $metadata;
169 }
170
178 function getMetadataType( $image ) {
179 return false;
180 }
181
198 public function isMetadataValid( $image, $metadata ) {
199 return self::METADATA_GOOD;
200 }
201
234 public function getCommonMetaArray( File $file ) {
235 return false;
236 }
237
250 function getScriptedTransform( $image, $script, $params ) {
251 return false;
252 }
253
264 final function getTransform( $image, $dstPath, $dstUrl, $params ) {
265 return $this->doTransform( $image, $dstPath, $dstUrl, $params, self::TRANSFORM_LATER );
266 }
267
280 abstract function doTransform( $image, $dstPath, $dstUrl, $params, $flags = 0 );
281
290 public function getThumbType( $ext, $mime, $params = null ) {
291 $magic = MediaWiki\MediaWikiServices::getInstance()->getMimeAnalyzer();
292 if ( !$ext || $magic->isMatchingExtension( $ext, $mime ) === false ) {
293 // The extension is not valid for this MIME type and we do
294 // recognize the MIME type
295 $extensions = $magic->getExtensionsForType( $mime );
296 if ( $extensions ) {
297 return [ strtok( $extensions, ' ' ), $mime ];
298 }
299 }
300
301 // The extension is correct (true) or the MIME type is unknown to
302 // MediaWiki (null)
303 return [ $ext, $mime ];
304 }
305
312 public function canRender( $file ) {
313 return true;
314 }
315
323 public function mustRender( $file ) {
324 return false;
325 }
326
333 public function isMultiPage( $file ) {
334 return false;
335 }
336
343 public function pageCount( File $file ) {
344 return false;
345 }
346
353 function isVectorized( $file ) {
354 return false;
355 }
356
365 function isAnimatedImage( $file ) {
366 return false;
367 }
368
377 return true;
378 }
379
384 public function isEnabled() {
385 return true;
386 }
387
404 public function getPageDimensions( File $image, $page ) {
405 $gis = $this->getImageSize( $image, $image->getLocalRefPath() );
406 if ( $gis ) {
407 return [
408 'width' => $gis[0],
409 'height' => $gis[1]
410 ];
411 } else {
412 return false;
413 }
414 }
415
424 function getPageText( File $image, $page ) {
425 return false;
426 }
427
433 public function getEntireText( File $file ) {
434 $numPages = $file->pageCount();
435 if ( !$numPages ) {
436 // Not a multipage document
437 return $this->getPageText( $file, 1 );
438 }
439 $document = '';
440 for ( $i = 1; $i <= $numPages; $i++ ) {
441 $curPage = $this->getPageText( $file, $i );
442 if ( is_string( $curPage ) ) {
443 $document .= $curPage . "\n";
444 }
445 }
446 if ( $document !== '' ) {
447 return $document;
448 }
449 return false;
450 }
451
480 public function formatMetadata( $image, $context = false ) {
481 return false;
482 }
483
494 function formatMetadataHelper( $metadataArray, $context = false ) {
495 $result = [
496 'visible' => [],
497 'collapsed' => []
498 ];
499
500 $formatted = FormatMetadata::getFormattedData( $metadataArray, $context );
501 // Sort fields into visible and collapsed
502 $visibleFields = $this->visibleMetadataFields();
503 foreach ( $formatted as $name => $value ) {
504 $tag = strtolower( $name );
505 self::addMeta( $result,
506 in_array( $tag, $visibleFields ) ? 'visible' : 'collapsed',
507 'exif',
508 $tag,
509 $value
510 );
511 }
512
513 return $result;
514 }
515
522 protected function visibleMetadataFields() {
524 }
525
549 protected static function addMeta( &$array, $visibility, $type, $id, $value, $param = false ) {
550 $msg = wfMessage( "$type-$id", $param );
551 if ( $msg->exists() ) {
552 $name = $msg->text();
553 } else {
554 // This is for future compatibility when using instant commons.
555 // So as to not display as ugly a name if a new metadata
556 // property is defined that we don't know about
557 // (not a major issue since such a property would be collapsed
558 // by default).
559 wfDebug( __METHOD__ . ' Unknown metadata name: ' . $id . "\n" );
560 $name = wfEscapeWikiText( $id );
561 }
562 $array[$visibility][] = [
563 'id' => "$type-$id",
564 'name' => $name,
565 'value' => $value
566 ];
567 }
568
575 function getShortDesc( $file ) {
577 }
578
585 public function getLongDesc( $file ) {
587 }
588
595 static function getGeneralShortDesc( $file ) {
596 global $wgLang;
597
598 return htmlspecialchars( $wgLang->formatSize( $file->getSize() ) );
599 }
600
607 static function getGeneralLongDesc( $file ) {
608 return wfMessage( 'file-info' )->sizeParams( $file->getSize() )
609 ->params( '<span class="mime-type">' . $file->getMimeType() . '</span>' )->parse();
610 }
611
620 public static function fitBoxWidth( $boxWidth, $boxHeight, $maxHeight ) {
621 $idealWidth = $boxWidth * $maxHeight / $boxHeight;
622 $roundedUp = ceil( $idealWidth );
623 if ( round( $roundedUp * $boxHeight / $boxWidth ) > $maxHeight ) {
624 return floor( $idealWidth );
625 } else {
626 return $roundedUp;
627 }
628 }
629
637 return '';
638 }
639
650 function parserTransformHook( $parser, $file ) {
651 }
652
663 public function verifyUpload( $fileName ) {
664 return Status::newGood();
665 }
666
675 function removeBadFile( $dstPath, $retval = 0 ) {
676 if ( file_exists( $dstPath ) ) {
677 $thumbstat = stat( $dstPath );
678 if ( $thumbstat['size'] == 0 || $retval != 0 ) {
679 $result = unlink( $dstPath );
680
681 if ( $result ) {
682 wfDebugLog( 'thumbnail',
683 sprintf( 'Removing bad %d-byte thumbnail "%s". unlink() succeeded',
684 $thumbstat['size'], $dstPath ) );
685 } else {
686 wfDebugLog( 'thumbnail',
687 sprintf( 'Removing bad %d-byte thumbnail "%s". unlink() failed',
688 $thumbstat['size'], $dstPath ) );
689 }
690
691 return true;
692 }
693 }
694
695 return false;
696 }
697
711 public function filterThumbnailPurgeList( &$files, $options ) {
712 // Do nothing
713 }
714
720 public function canRotate() {
721 return false;
722 }
723
738 public function getRotation( $file ) {
739 return 0;
740 }
741
753 protected function logErrorForExternalProcess( $retval, $err, $cmd ) {
754 # Keep error output limited (T59985)
755 $errMessage = trim( substr( $err, 0, self::MAX_ERR_LOG_SIZE ) );
756
757 wfDebugLog( 'thumbnail',
758 sprintf( 'thumbnail failed on %s: error %d "%s" from "%s"',
759 wfHostname(), $retval, $errMessage, $cmd ) );
760 }
761
769 public function getAvailableLanguages( File $file ) {
770 return [];
771 }
772
782 public function getMatchedLanguage( $userPreferredLanguage, array $availableLanguages ) {
783 return null;
784 }
785
799 return null;
800 }
801
812 public function getLength( $file ) {
813 return 0.0;
814 }
815
821 public function isExpensiveToThumbnail( $file ) {
822 return false;
823 }
824
831 public function supportsBucketing() {
832 return false;
833 }
834
841 public function sanitizeParamsForBucketing( $params ) {
842 return $params;
843 }
844
870 public function getWarningConfig( $file ) {
871 return null;
872 }
873
881 public static function getPageRangesByDimensions( $pagesByDimensions ) {
882 $pageRangesByDimensions = [];
883
884 foreach ( $pagesByDimensions as $dimensions => $pageList ) {
885 $ranges = [];
886 $firstPage = $pageList[0];
887 $lastPage = $firstPage - 1;
888
889 foreach ( $pageList as $page ) {
890 if ( $page > $lastPage + 1 ) {
891 if ( $firstPage != $lastPage ) {
892 $ranges[] = "$firstPage-$lastPage";
893 } else {
894 $ranges[] = "$firstPage";
895 }
896
897 $firstPage = $page;
898 }
899
900 $lastPage = $page;
901 }
902
903 if ( $firstPage != $lastPage ) {
904 $ranges[] = "$firstPage-$lastPage";
905 } else {
906 $ranges[] = "$firstPage";
907 }
908
909 $pageRangesByDimensions[ $dimensions ] = $ranges;
910 }
911
912 $dimensionsString = [];
913 foreach ( $pageRangesByDimensions as $dimensions => $pageRanges ) {
914 $dimensionsString[] = "$dimensions:" . implode( ',', $pageRanges );
915 }
916
917 return implode( '/', $dimensionsString );
918 }
919
926 public function getContentHeaders( $metadata ) {
927 return [ 'X-Content-Dimensions' => '' ]; // T175689
928 }
929}
unserialize( $serialized)
wfDebug( $text, $dest='all', array $context=[])
Sends a line to the debug log if enabled or, optionally, to a comment in output.
wfHostname()
Get host name of the current machine, for use in error reporting.
wfDebugLog( $logGroup, $text, $dest='all', array $context=[])
Send a line to a supplementary debug log file, if configured, or main debug log if not.
wfMessage( $key,... $params)
This is the function for getting translated interface messages.
wfEscapeWikiText( $text)
Escapes the given text so that it may be output using addWikiText() without any linking,...
$wgLang
Definition Setup.php:880
Implements some public methods and some protected utility functions which are required by multiple ch...
Definition File.php:61
getLocalRefPath()
Get an FS copy or original of this file and return the path.
Definition File.php:443
static getVisibleFields()
Get a list of fields that are visible by default.
static getFormattedData( $tags, $context=false)
Numbers given by Exif user agents are often magical, that is they should be replaced by a detailed ex...
Base media handler class.
normaliseParams( $image, &$params)
Changes the parameter array as necessary, ready for transformation.
getRotation( $file)
On supporting image formats, try to read out the low-level orientation of the file and return the ang...
const METADATA_COMPATIBLE
canRender( $file)
True if the handled types can be transformed.
canAnimateThumbnail( $file)
If the material is animated, we can animate the thumbnail.
verifyUpload( $fileName)
File validation hook called on upload.
visibleMetadataFields()
Get a list of metadata items which should be displayed when the metadata table is collapsed.
static addMeta(&$array, $visibility, $type, $id, $value, $param=false)
This is used to generate an array element for each metadata value That array is then used to generate...
supportsBucketing()
Returns whether or not this handler supports the chained generation of thumbnails according to bucket...
parserTransformHook( $parser, $file)
Modify the parser object post-transform.
static getGeneralLongDesc( $file)
Used instead of getLongDesc if there is no handler registered for file.
canRotate()
True if the handler can rotate the media.
sanitizeParamsForBucketing( $params)
Returns a normalised params array for which parameters have been cleaned up for bucketing purposes.
getDefaultRenderLanguage(File $file)
On file types that support renderings in multiple languages, which language is used by default if uns...
getLength( $file)
If its an audio file, return the length of the file.
getTransform( $image, $dstPath, $dstUrl, $params)
Get a MediaTransformOutput object representing the transformed output.
getDimensionsString( $file)
Shown in file history box on image description page.
static getHandler( $type)
Get a MediaHandler for a given MIME type from the instance cache.
getCommonMetaArray(File $file)
Get an array of standard (FormatMetadata type) metadata values.
doTransform( $image, $dstPath, $dstUrl, $params, $flags=0)
Get a MediaTransformOutput object representing the transformed output.
getMetadata( $image, $path)
Get handler-specific metadata which will be saved in the img_metadata field.
getPageText(File $image, $page)
Generic getter for text layer.
isAnimatedImage( $file)
The material is an image, and is animated.
isVectorized( $file)
The material is vectorized and thus scaling is lossless.
getImageSize( $image, $path)
Get an image size array like that returned by getimagesize(), or false if it can't be determined.
convertMetadataVersion( $metadata, $version=1)
Convert metadata version.
formatMetadata( $image, $context=false)
Get an array structure that looks like this:
getWarningConfig( $file)
Gets configuration for the file warning message.
logErrorForExternalProcess( $retval, $err, $cmd)
Log an error that occurred in an external process.
isEnabled()
False if the handler is disabled for all files.
parseParamString( $str)
Parse a param string made with makeParamString back into an array.
static getGeneralShortDesc( $file)
Used instead of getShortDesc if there is no handler registered for file.
isMultiPage( $file)
True if the type has multi-page capabilities.
getLongDesc( $file)
Long description.
static fitBoxWidth( $boxWidth, $boxHeight, $maxHeight)
Calculate the largest thumbnail width for a given original file size such that the thumbnail's height...
mustRender( $file)
True if handled types cannot be displayed directly in a browser but can be rendered.
getScriptedTransform( $image, $script, $params)
Get a MediaTransformOutput object representing an alternate of the transformed output which will call...
getMetadataType( $image)
Get a string describing the type of metadata, for display purposes.
isExpensiveToThumbnail( $file)
True if creating thumbnails from the file is large or otherwise resource-intensive.
getEntireText(File $file)
Get the text of the entire document.
getAvailableLanguages(File $file)
Get list of languages file can be viewed in.
filterThumbnailPurgeList(&$files, $options)
Remove files from the purge list.
getShortDesc( $file)
Short description.
makeParamString( $params)
Merge a parameter array into a string appropriate for inclusion in filenames.
formatMetadataHelper( $metadataArray, $context=false)
sorts the visible/invisible field.
validateParam( $name, $value)
Validate a thumbnail parameter at parse time.
static getPageRangesByDimensions( $pagesByDimensions)
Converts a dimensions array about a potentially multipage document from an exhaustive list of ordered...
getPageDimensions(File $image, $page)
Get an associative array of page dimensions Currently "width" and "height" are understood,...
getContentHeaders( $metadata)
Get useful response headers for GET/HEAD requests for a file with the given metadata.
const TRANSFORM_LATER
getParamMap()
Get an associative array mapping magic word IDs to parameter names.
const MAX_ERR_LOG_SIZE
Max length of error logged by logErrorForExternalProcess()
const METADATA_GOOD
getThumbType( $ext, $mime, $params=null)
Get the thumbnail extension and MIME type for a given source MIME type.
removeBadFile( $dstPath, $retval=0)
Check for zero-sized thumbnails.
isMetadataValid( $image, $metadata)
Check if the metadata string is valid for this handler.
getMatchedLanguage( $userPreferredLanguage, array $availableLanguages)
When overridden in a descendant class, returns a language code most suiting.
static getMetadataVersion()
Get metadata version.
pageCount(File $file)
Page count for a multi-page document, false if unsupported or unknown.
MediaWikiServices is the service locator for the application scope of MediaWiki.
$context
Definition load.php:45
if(PHP_SAPI !='cli-server') if(!isset( $_SERVER['SCRIPT_FILENAME'])) $file
Item class for a filearchive table row.
Definition router.php:42
if(!is_readable( $file)) $ext
Definition router.php:48