Base media handler class. More...

Inherited by ImageHandler.

Public Member Functions
	canAnimateThumbnail ( $file)
	If the material is animated, we can animate the thumbnail.

	canRender ( $file)
	True if the handled types can be transformed.

	canRotate ()
	True if the handler can rotate the media.

	convertMetadataVersion ( $metadata, $version=1)
	Convert metadata version.

	doTransform ( $image, $dstPath, $dstUrl, $params, $flags=0)
	Get a MediaTransformOutput object representing the transformed output.

	filterThumbnailPurgeList (&$files, $options)
	Remove files from the purge list.

	formatMetadata ( $image, $context=false)
	Get an array structure that looks like this:

	getAvailableLanguages (File $file)
	Get list of languages file can be viewed in.

	getCommonMetaArray (File $file)
	Get an array of standard (FormatMetadata type) metadata values.

	getContentHeaders ( $metadata)
	Get useful response headers for GET/HEAD requests for a file with the given metadata.

	getDefaultRenderLanguage (File $file)
	On file types that support renderings in multiple languages, which language is used by default if unspecified.

	getDimensionsString ( $file)
	Shown in file history box on image description page.

	getEntireText (File $file)
	Get the text of the entire document.

	getImageSize ( $image, $path)
	Get an image size array like that returned by getimagesize(), or false if it can't be determined.

	getLength ( $file)
	If it's an audio file, return the length of the file.

	getLongDesc ( $file)
	Long description.

	getMatchedLanguage ( $userPreferredLanguage, array $availableLanguages)
	When overridden in a descendant class, returns a language code most suiting.

	getMetadata ( $image, $path)
	Get handler-specific metadata which will be saved in the img_metadata field.

	getMetadataType ( $image)
	Get a string describing the type of metadata, for display purposes.

	getPageDimensions (File $image, $page)
	Get an associative array of page dimensions Currently "width" and "height" are understood, but this might be expanded in the future.

	getPageText (File $image, $page)
	Generic getter for text layer.

	getParamMap ()
	Get an associative array mapping magic word IDs to parameter names.

	getRotation ( $file)
	On supporting image formats, try to read out the low-level orientation of the file and return the angle that the file needs to be rotated to be viewed.

	getScriptedTransform ( $image, $script, $params)
	Get a MediaTransformOutput object representing an alternate of the transformed output which will call an intermediary thumbnail assist script.

	getShortDesc ( $file)
	Short description.

	getSizeAndMetadata ( $state, $path)
	Get image size information and metadata array.

	getSizeAndMetadataWithFallback ( $file, $path)
	Get the metadata array and the image size, with b/c fallback.

	getThumbType ( $ext, $mime, $params=null)
	Get the thumbnail extension and MIME type for a given source MIME type.

	getTransform ( $image, $dstPath, $dstUrl, $params)
	Get a MediaTransformOutput object representing the transformed output.

	getWarningConfig ( $file)
	Gets configuration for the file warning message.

	isAnimatedImage ( $file)
	The material is an image, and is animated.

	isEnabled ()
	False if the handler is disabled for all files.

	isExpensiveToThumbnail ( $file)
	True if creating thumbnails from the file is large or otherwise resource-intensive.

	isFileMetadataValid ( $image)
	Check if the metadata is valid for this handler.

	isMetadataValid ( $image, $metadata)
	Check if the metadata string is valid for this handler.

	isMultiPage ( $file)
	True if the type has multi-page capabilities.

	isVectorized ( $file)
	The material is vectorized and thus scaling is lossless.

	makeParamString ( $params)
	Merge a parameter array into a string appropriate for inclusion in filenames.

	mustRender ( $file)
	True if handled types cannot be displayed directly in a browser but can be rendered.

	normaliseParams ( $image, &$params)
	Changes the parameter array as necessary, ready for transformation.

	pageCount (File $file)
	Page count for a multi-page document, false if unsupported or unknown.

	parseParamString ( $str)
	Parse a param string made with makeParamString back into an array.

	parserTransformHook ( $parser, $file)
	Modify the parser object post-transform.

	removeBadFile ( $dstPath, $retval=0)
	Check for zero-sized thumbnails.

	sanitizeParamsForBucketing ( $params)
	Returns a normalised params array for which parameters have been cleaned up for bucketing purposes.

	supportsBucketing ()
	Returns whether or not this handler supports the chained generation of thumbnails according to buckets.

	useSplitMetadata ()
	If this returns true, LocalFile may split metadata up and store its constituent items separately.

	validateParam ( $name, $value)
	Validate a thumbnail parameter at parse time.

	verifyUpload ( $fileName)
	File validation hook called on upload.

Static Public Member Functions
static	fitBoxWidth ( $boxWidth, $boxHeight, $maxHeight)
	Calculate the largest thumbnail width for a given original file size such that the thumbnail's height is at most $maxHeight.

static	getGeneralLongDesc ( $file)
	Used instead of getLongDesc if there is no handler registered for file.

static	getGeneralShortDesc ( $file)
	Used instead of getShortDesc if there is no handler registered for file.

static	getHandler ( $type)
	Get a MediaHandler for a given MIME type from the instance cache.

static	getMetadataVersion ()
	Get metadata version.

static	getPageRangesByDimensions ( $pagesByDimensions)
	Converts a dimensions array about a potentially multipage document from an exhaustive list of ordered page numbers to a list of page ranges.

Public Attributes
const	METADATA_BAD = false

const	METADATA_COMPATIBLE = 2

const	METADATA_GOOD = true

const	TRANSFORM_LATER = 1

Protected Member Functions
	formatMetadataHelper ( $metadataArray, $context=false)
	sorts the visible/invisible field.

	formatTag (string $key, $vals, $context=false)
	Override default formatting for the given metadata field.

	hasMostDerivedMethod ( $name)
	Check whether a method is implemented in the most derived class.

	logErrorForExternalProcess ( $retval, $err, $cmd)
	Log an error that occurred in an external process.

	useLegacyMetadata ()
	If this returns true, the new method getSizeAndMetadata() will not be called.

	visibleMetadataFields ()
	Get a list of metadata items which should be displayed when the metadata table is collapsed.

Static Protected Member Functions
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 the table of metadata values on the image page.

Detailed Description

Base media handler class.

Stability: stable: to extend

Definition at line 38 of file MediaHandler.php.

Member Function Documentation

◆ addMeta()

static MediaHandler::addMeta	(	&	$array,
			$visibility,
			$type,
			$id,
			$value,
			$param = false )

staticprotected

This is used to generate an array element for each metadata value That array is then used to generate the table of metadata values on the image page.

Parameters

array	&$array	An array containing elements for each type of visibility and each of those elements being an array of metadata items. This function adds a value to that array.
string	$visibility	('visible' or 'collapsed') if this value is hidden by default.
string	$type	Type of metadata tag (currently always 'exif')
string	$id	The name of the metadata tag (like 'artist' for example). its name in the table displayed is the message "$type-$id" (Ex exif-artist ).
string	$value	Thingy goes into a wikitext table; it used to be escaped but that was incompatible with previous practise of customized display with wikitext formatting via messages such as 'exif-model-value'. So the escaping is taken back out, but generally this seems a confusing interface.
bool \| string	$param	Value to pass to the message for the name of the field as $1. Currently this parameter doesn't seem to ever be used.

Note, everything here is passed through the parser later on (!)

Definition at line 790 of file MediaHandler.php.

References wfDebug(), wfEscapeWikiText(), and wfMessage().

Referenced by formatMetadataHelper().

◆ canAnimateThumbnail()

MediaHandler::canAnimateThumbnail ( $file )

If the material is animated, we can animate the thumbnail.

Since: 1.20

Stability: stable: to override

Parameters

File $file

Returns: bool If material is not animated, handler may return any value.

Reimplemented in GIFHandler, SvgHandler, WebPHandler, and PNGHandler.

Definition at line 578 of file MediaHandler.php.

Referenced by File\canAnimateThumbIfAppropriate().

◆ canRender()

MediaHandler::canRender ( $file )

True if the handled types can be transformed.

Stability: stable: to override

Parameters

File $file

Returns: bool

Reimplemented in ImageHandler, TiffHandler, WebPHandler, and XCFHandler.

Definition at line 502 of file MediaHandler.php.

◆ canRotate()

MediaHandler::canRotate ( )

True if the handler can rotate the media.

Since: 1.24 non-static. From 1.21-1.23 was static

Stability: stable: to override

Returns: bool

Reimplemented in BitmapHandler, and TransformationalImageHandler.

Definition at line 975 of file MediaHandler.php.

◆ convertMetadataVersion()

MediaHandler::convertMetadataVersion	(		$metadata,
			$version = 1 )

Convert metadata version.

By default just returns $metadata, but can be used to allow media handlers to convert between metadata versions.

Stability: stable: to override

Parameters

array	$metadata	Metadata array
int \| string	$version	Target version

Returns: array Serialized metadata in specified version, or $metadata on fail.

Reimplemented in ExifBitmapHandler.

Definition at line 312 of file MediaHandler.php.

Referenced by File\convertMetadataVersion().

◆ doTransform()

MediaHandler::doTransform	(	$image,
		$dstPath,
		$dstUrl,
		$params,
		$flags = 0 )

abstract

Get a MediaTransformOutput object representing the transformed output.

Does the transform unless $flags contains self::TRANSFORM_LATER.

Stability: stable: to override

Parameters

File	$image
string	$dstPath	Filesystem destination path
string	$dstUrl	Destination URL to use in output HTML
array	$params	Arbitrary set of parameters validated by $this->validateParam() Note: These parameters have not gone through $this->normaliseParams()
int	$flags	A bitfield, may contain self::TRANSFORM_LATER

Returns: MediaTransformOutput

Reimplemented in BitmapHandler_ClientOnly, DjVuHandler, SvgHandler, and TransformationalImageHandler.

Referenced by File\generateAndSaveThumb(), and getTransform().

◆ filterThumbnailPurgeList()

MediaHandler::filterThumbnailPurgeList	(	&	$files,
			$options )

Remove files from the purge list.

This is used by some video handlers to prevent ?action=purge from removing a transcoded video, which is expensive to regenerate.

See also: LocalFile::purgeThumbnails

Stability: stable: to override

Parameters

array	&$files
array	$options	Purge options. Currently will always be an array with a single key 'forThumbRefresh' set to true.

Definition at line 964 of file MediaHandler.php.

◆ fitBoxWidth()

static MediaHandler::fitBoxWidth	(	$boxWidth,
		$boxHeight,
		$maxHeight )

static

Calculate the largest thumbnail width for a given original file size such that the thumbnail's height is at most $maxHeight.

Parameters

int	$boxWidth	Width of the thumbnail box.
int	$boxHeight	Height of the thumbnail box.
int	$maxHeight	Maximum height expected for the thumbnail.

Returns: int

Definition at line 865 of file MediaHandler.php.

Referenced by ImageHandler\normaliseParams().

◆ formatMetadata()

MediaHandler::formatMetadata	(		$image,
			$context = false )

Get an array structure that looks like this:

[ 'visible' => [ 'Human-readable name' => 'Human readable value', ... ], 'collapsed' => [ 'Human-readable name' => 'Human readable value', ... ] ] The UI will format this into a table where the visible fields are always visible, and the collapsed fields are optionally visible.

The function should return false if there is no metadata to display.

Todo: FIXME: This interface is not very flexible. The media handler should generate HTML instead. It can do all the formatting according to some standard. That makes it possible to do things like visual indication of grouped and chained streams in ogg container files.

Stability: stable: to override

Parameters

File	$image
IContextSource \| false	$context

Returns: array|false

Reimplemented in SvgHandler, ExifBitmapHandler, GIFHandler, and PNGHandler.

Definition at line 681 of file MediaHandler.php.

Referenced by File\formatMetadata().

◆ formatMetadataHelper()

MediaHandler::formatMetadataHelper	(		$metadataArray,
			$context = false )

protected

sorts the visible/invisible field.

Split off from ImageHandler::formatMetadata, as used by more than one type of handler.

This is used by the media handlers that use the FormatMetadata class

Stability: stable: to override

Parameters

array	$metadataArray
IContextSource \| false	$context

Returns: array[] Array for use displaying metadata.

Definition at line 697 of file MediaHandler.php.

References addMeta(), formatTag(), FormatMetadata\getFormattedData(), and visibleMetadataFields().

Referenced by ExifBitmapHandler\formatMetadata(), GIFHandler\formatMetadata(), and PNGHandler\formatMetadata().

◆ formatTag()

MediaHandler::formatTag	(	string	$key,
			$vals,
			$context = false )

protected

Override default formatting for the given metadata field.

Stability: stable: to override

Parameters

string	$key	The metadata field key
string \| array	$vals	The unformatted value of this metadata field
IContextSource \| false	$context	Context to use (optional)

Returns: false|null|string|array False to use default formatting, null to remove this tag from the formatted list; otherwise return a formatted HTML string (or array of them).

Definition at line 751 of file MediaHandler.php.

Referenced by formatMetadataHelper().

◆ getAvailableLanguages()

MediaHandler::getAvailableLanguages ( File $file )

Get list of languages file can be viewed in.

Stability: stable: to override

Parameters

File $file

Returns: string[] Array of IETF language codes, or empty array if unsupported.

Since: 1.23

Reimplemented in SvgHandler.

Definition at line 1028 of file MediaHandler.php.

Referenced by File\getAvailableLanguages(), and File\getMatchedLanguage().

◆ getCommonMetaArray()

MediaHandler::getCommonMetaArray ( File $file )

Get an array of standard (FormatMetadata type) metadata values.

The returned data is largely the same as that from getMetadata(), but formatted in a standard, stable, handler-independent way. The idea being that some values like ImageDescription or Artist are universal and should be retrievable in a handler generic way.

The specific properties are the type of properties that can be handled by the FormatMetadata class. These values are exposed to the user via the filemetadata parser function.

Details of the response format of this function can be found at https://www.mediawiki.org/wiki/Manual:File_metadata_handling tl/dr: the response is an associative array of properties keyed by name, but the value can be complex. You probably want to call one of the FormatMetadata::flatten* functions on the property values before using them, or call FormatMetadata::getFormattedData() on the full response array, which transforms all values into prettified, human-readable text.

Subclasses overriding this function must return a value which is a valid API response fragment (all associative array keys are valid XML tagnames).

Note, if the file simply has no metadata, but the handler supports this interface, it should return an empty array, not false.

Stability: stable: to override

Parameters

File $file

Returns: array|false False if interface not supported

Since: 1.23

Reimplemented in ExifBitmapHandler, SvgHandler, GIFHandler, and PNGHandler.

Definition at line 413 of file MediaHandler.php.

Referenced by File\getCommonMetaArray().

◆ getContentHeaders()

MediaHandler::getContentHeaders ( $metadata )

Get useful response headers for GET/HEAD requests for a file with the given metadata.

Stability: stable: to override

Parameters

array $metadata Contains this handler's unserialized getMetadata() for a file

Returns: array

Since: 1.30

Definition at line 1201 of file MediaHandler.php.

Referenced by File\getContentHeaders().

◆ getDefaultRenderLanguage()

MediaHandler::getDefaultRenderLanguage ( File $file )

On file types that support renderings in multiple languages, which language is used by default if unspecified.

If getAvailableLanguages returns a non-empty array, this must return a valid language code. Otherwise can return null if files of this type do not support alternative language renderings. It can also return 'und' for explicitly requesting an undetermined language

Stability: stable: to override

Parameters

File $file

Returns: string|null IETF Language code or null if multi-language not supported for filetype.

Since: 1.23

Reimplemented in SvgHandler.

Definition at line 1062 of file MediaHandler.php.

Referenced by File\getDefaultRenderLanguage().

◆ getDimensionsString()

MediaHandler::getDimensionsString ( $file )

Shown in file history box on image description page.

Stability: stable: to override

Parameters

File $file

Returns: string Dimensions

Reimplemented in ImageHandler.

Definition at line 882 of file MediaHandler.php.

Referenced by File\getDimensionsString().

◆ getEntireText()

MediaHandler::getEntireText ( File $file )

Get the text of the entire document.

Parameters

File $file

Returns: string|false The text of the document or false if unsupported.

Definition at line 632 of file MediaHandler.php.

References $file, and getPageText().

◆ getGeneralLongDesc()

static MediaHandler::getGeneralLongDesc ( $file )

static

Used instead of getLongDesc if there is no handler registered for file.

Parameters

File $file

Returns: string

Definition at line 852 of file MediaHandler.php.

References $file, and wfMessage().

Referenced by getLongDesc(), and File\getLongDesc().

◆ getGeneralShortDesc()

static MediaHandler::getGeneralShortDesc ( $file )

static

Used instead of getShortDesc if there is no handler registered for file.

Parameters

File $file

Returns: string

Definition at line 840 of file MediaHandler.php.

References $file, and $wgLang.

Referenced by getShortDesc(), and File\getShortDesc().

◆ getHandler()

static MediaHandler::getHandler ( $type )

static

Get a MediaHandler for a given MIME type from the instance cache.

Parameters

string $type

Returns: MediaHandler|false

Definition at line 54 of file MediaHandler.php.

References $type.

Referenced by ImportImages\execute(), File\getHandler(), MWFileProps\getPropsFromPath(), LocalFile\upload(), and UploadBase\verifyFile().

◆ getImageSize()

MediaHandler::getImageSize	(		$image,
			$path )

Get an image size array like that returned by getimagesize(), or false if it can't be determined.

This function is used for determining the width, height and bitdepth directly from an image. The results are stored in the database in the img_width, img_height, img_bits fields.

Note: If this is a multipage file, return the width and height of the first page.

Deprecated: since 1.37, override getSizeAndMetadata instead

Parameters

File \| FSFile \| false	$image	The image object, or false if there isn't one. Warning, FSFile::getPropsFromPath might pass an FSFile instead of File (!)
string	$path	The filename

Returns: array|false Follow the format of PHP getimagesize() internal function. See https://www.php.net/getimagesize. MediaWiki will only ever use the first two array keys (the width and height), and the 'bits' associative key. All other array keys are ignored. Returning a 'bits' key is optional as not all formats have a notion of "bitdepth". Returns false on failure.

Reimplemented in ImageHandler.

Definition at line 125 of file MediaHandler.php.

Referenced by getSizeAndMetadataWithFallback().

◆ getLength()

MediaHandler::getLength ( $file )

If it's an audio file, return the length of the file.

Otherwise 0.

File::getLength() existed for a long time, but was calling a method that only existed in some subclasses of this class (The TMH ones).

Stability: stable: to override

Parameters

File $file

Returns: float Length in seconds

Since: 1.23

Reimplemented in GIFHandler, and PNGHandler.

Definition at line 1078 of file MediaHandler.php.

Referenced by File\getLength().

◆ getLongDesc()

MediaHandler::getLongDesc ( $file )

Long description.

Shown under image on image description page surrounded by ().

Stability: stable: to override

Parameters

File $file

Returns: string

Reimplemented in ImageHandler, SvgHandler, GIFHandler, and PNGHandler.

Definition at line 830 of file MediaHandler.php.

References $file, and getGeneralLongDesc().

Referenced by File\getLongDesc().

◆ getMatchedLanguage()

MediaHandler::getMatchedLanguage	(		$userPreferredLanguage,
		array	$availableLanguages )

When overridden in a descendant class, returns a language code most suiting.

Stability: stable: to override

Since: 1.32

Parameters

string	$userPreferredLanguage	IETF Language code requested
string[]	$availableLanguages	IETF Languages present in the file

Returns: string|null IETF Language code picked or null if not supported/available

Reimplemented in SvgHandler.

Definition at line 1043 of file MediaHandler.php.

Referenced by File\getMatchedLanguage().

◆ getMetadata()

MediaHandler::getMetadata	(		$image,
			$path )

Get handler-specific metadata which will be saved in the img_metadata field.

Deprecated: since 1.37 override getSizeAndMetadata() instead

Parameters

File \| FSFile \| false	$image	The image object, or false if there isn't one. Warning, FSFile::getPropsFromPath might pass an FSFile instead of File (!)
string	$path	The filename

Returns: string A string of metadata in php serialized form (Run through serialize())

Definition at line 167 of file MediaHandler.php.

Referenced by getSizeAndMetadataWithFallback().

◆ getMetadataType()

MediaHandler::getMetadataType ( $image )

Get a string describing the type of metadata, for display purposes.

Stability: stable: to override

Note: This method is currently unused.

Parameters

File $image

Returns: string|false

Reimplemented in DjVuHandler, ExifBitmapHandler, GIFHandler, PNGHandler, SvgHandler, and WebPHandler.

Definition at line 324 of file MediaHandler.php.

◆ getMetadataVersion()

static MediaHandler::getMetadataVersion ( )

static

Get metadata version.

This is not used for validating metadata, this is used for the api when returning metadata, since api content formats should stay the same over time, and so things using ForeignApiRepo can keep backwards compatibility

All core media handlers share a common version number, and extensions can use the GetMetadataVersion hook to append to the array (they should append a unique string so not to get confusing). If there was a media handler named 'foo' with metadata version 3 it might add to the end of the array the element 'foo=3'. if the core metadata version is 2, the end version string would look like '2;foo=3'.

Stability: stable: to override

Returns: string Version string

Definition at line 294 of file MediaHandler.php.

Referenced by ForeignAPIFile\newFromTitle().

◆ getPageDimensions()

MediaHandler::getPageDimensions	(	File	$image,
			$page )

Get an associative array of page dimensions Currently "width" and "height" are understood, but this might be expanded in the future.

Returns false if unknown.

For a single page document format (!isMultipage()), this should return false.

Note: For non-paged media, use getImageSize.

Stability: stable: to override

Parameters

File	$image
int	$page	What page to get dimensions of

Returns: array|false

Reimplemented in DjVuHandler.

Definition at line 609 of file MediaHandler.php.

Referenced by LocalFile\getHeight(), and LocalFile\getWidth().

◆ getPageRangesByDimensions()

static MediaHandler::getPageRangesByDimensions ( $pagesByDimensions )

static

Converts a dimensions array about a potentially multipage document from an exhaustive list of ordered page numbers to a list of page ranges.

Parameters

array[] $pagesByDimensions

Returns: string

Since: 1.30

Definition at line 1154 of file MediaHandler.php.

◆ getPageText()

MediaHandler::getPageText	(	File	$image,
			$page )

Generic getter for text layer.

Currently overloaded by PDF and DjVu handlers

Stability: stable: to override

Parameters

File	$image
int	$page	Page number to get information for

Returns: string|false Page text or false when no text found or if unsupported.

Reimplemented in DjVuHandler.

Definition at line 623 of file MediaHandler.php.

Referenced by getEntireText().

◆ getParamMap()

MediaHandler::getParamMap ( )

abstract

Get an associative array mapping magic word IDs to parameter names.

Will be used by the parser to identify parameters.

Returns: string[]

Reimplemented in DjVuHandler, ImageHandler, and SvgHandler.

◆ getRotation()

MediaHandler::getRotation ( $file )

On supporting image formats, try to read out the low-level orientation of the file and return the angle that the file needs to be rotated to be viewed.

This information is only useful when manipulating the original file; the width and height we normally work with is logical, and will match any produced output views.

For files we don't know, we return 0.

Stability: stable: to override

Parameters

File $file

Returns: int 0, 90, 180 or 270

Reimplemented in ExifBitmapHandler.

Definition at line 995 of file MediaHandler.php.

Referenced by TransformationalImageHandler\mustRender(), BitmapHandler\rotate(), BitmapHandler\transformGd(), BitmapHandler\transformImageMagick(), and BitmapHandler\transformImageMagickExt().

◆ getScriptedTransform()

MediaHandler::getScriptedTransform	(	$image,
		$script,
		$params )

Get a MediaTransformOutput object representing an alternate of the transformed output which will call an intermediary thumbnail assist script.

Used when the repository has a thumbnailScriptUrl option configured.

Return false to fall back to the regular getTransform().

Stability: stable: to override

Parameters

File	$image
string	$script
array	$params

Returns: ThumbnailImage|false

Reimplemented in ImageHandler.

Definition at line 432 of file MediaHandler.php.

Referenced by File\transform().

◆ getShortDesc()

MediaHandler::getShortDesc ( $file )

Short description.

Shown on Special:Search results.

Stability: stable: to override

Parameters

File $file

Returns: string

Reimplemented in ImageHandler.

Definition at line 818 of file MediaHandler.php.

References $file, and getGeneralShortDesc().

Referenced by File\getShortDesc().

◆ getSizeAndMetadata()

MediaHandler::getSizeAndMetadata	(		$state,
			$path )

Get image size information and metadata array.

If this returns null, the caller will fall back to getImageSize() and getMetadata().

If getImageSize() or getMetadata() are implemented in the most derived class, they will be used instead of this function. To override this behaviour, override useLegacyMetadata().

Stability: stable: to override

Since: 1.37

Parameters

MediaHandlerState	$state	An object for saving process-local state. This is normally a File object which will be passed back to other MediaHandler methods like pageCount(), if they are called in the same request. The handler can use this object to save its state.
string	$path	The filename

Returns

array|null Null to fall back to getImageSize(), or an array with the following keys. All keys are optional.

width: The width. If multipage, return the first page width. (optional)
height: The height. If multipage, return the first page height. (optional)
bits: The number of bits for each color (optional)
metadata: A JSON-serializable array of metadata (optional)

Reimplemented in BmpHandler, GIFHandler, JpegHandler, PNGHandler, SvgHandler, TiffHandler, WebPHandler, XCFHandler, DjVuHandler, and ImageHandler.

Definition at line 154 of file MediaHandler.php.

Referenced by getSizeAndMetadataWithFallback().

◆ getSizeAndMetadataWithFallback()

MediaHandler::getSizeAndMetadataWithFallback	(		$file,
			$path )

final

Get the metadata array and the image size, with b/c fallback.

The legacy methods will be used if useLegacyMetadata() returns true or if getSizeAndMetadata() returns null.

Absent metadata will be normalized to an empty array. Absent width and height will be normalized to zero.

Parameters

File \| FSFile	$file	This must be a File or FSFile to support the legacy methods. When the legacy methods are removed, this will be narrowed to MediaHandlerState.
string	$path

Returns

array|false|null False on failure, or an array with the following keys:

width: The width. If multipage, return the first page width.
height: The height. If multipage, return the first page height.
bits: The number of bits for each color (optional)
metadata: A JSON-serializable array of metadata

Since: 1.37

Definition at line 218 of file MediaHandler.php.

References $blob, $file, $path, getImageSize(), getMetadata(), getSizeAndMetadata(), and useLegacyMetadata().

◆ getThumbType()

MediaHandler::getThumbType	(	$ext,
		$mime,
		$params = null )

Get the thumbnail extension and MIME type for a given source MIME type.

Stability: stable: to override

Parameters

string	$ext	Extension of original file
string	$mime	MIME type of original file
array \| null	$params	Handler specific rendering parameters

Returns: array Thumbnail extension and MIME type

Reimplemented in BmpHandler, DjVuHandler, Jpeg2000Handler, SvgHandler, TiffHandler, WebPHandler, and XCFHandler.

Definition at line 478 of file MediaHandler.php.

References $ext, and $mime.

◆ getTransform()

MediaHandler::getTransform	(	$image,
		$dstPath,
		$dstUrl,
		$params )

final

Get a MediaTransformOutput object representing the transformed output.

Does not actually do the transform.

Stability: stable: to override

Parameters

File	$image
string	$dstPath	Filesystem destination path
string	$dstUrl	Destination URL to use in output HTML
array	$params	Arbitrary set of parameters validated by $this->validateParam()

Returns: MediaTransformOutput

Definition at line 448 of file MediaHandler.php.

References doTransform().

Referenced by File\generateAndSaveThumb(), File\transform(), and File\transformErrorOutput().

◆ getWarningConfig()

MediaHandler::getWarningConfig ( $file )

Gets configuration for the file warning message.

Return value of the following structure: [ // Required, module with messages loaded for the client 'module' => 'example.filewarning.messages', // Required, array of names of messages 'messages' => [ // Required, main warning message 'main' => 'example-filewarning-main', // Optional, header for warning dialog 'header' => 'example-filewarning-header', // Optional, footer for warning dialog 'footer' => 'example-filewarning-footer', // Optional, text for more-information link (see below) 'info' => 'example-filewarning-info', ], // Optional, link for more information 'link' => 'http://example.com', ]

Returns null if no warning is necessary.

Stability: stable: to override

Parameters

File $file

Returns: array|null

Definition at line 1143 of file MediaHandler.php.

◆ hasMostDerivedMethod()

MediaHandler::hasMostDerivedMethod ( $name )

protected

Check whether a method is implemented in the most derived class.

Since: 1.37

Parameters

string $name

Returns: bool

Definition at line 192 of file MediaHandler.php.

Referenced by useLegacyMetadata().

◆ isAnimatedImage()

MediaHandler::isAnimatedImage ( $file )

The material is an image, and is animated.

In particular, video material need not return true.

Note: Before 1.20, this was a method of ImageHandler only

Stability: stable: to override

Parameters

File $file

Returns: bool

Reimplemented in SvgHandler, GIFHandler, PNGHandler, and WebPHandler.

Definition at line 565 of file MediaHandler.php.

Referenced by File\canAnimateThumbIfAppropriate(), BitmapHandler\transformImageMagick(), and BitmapHandler\transformImageMagickExt().

◆ isEnabled()

MediaHandler::isEnabled ( )

False if the handler is disabled for all files.

Stability: stable: to override

Returns: bool

Reimplemented in DjVuHandler, and SvgHandler.

Definition at line 588 of file MediaHandler.php.

◆ isExpensiveToThumbnail()

MediaHandler::isExpensiveToThumbnail ( $file )

True if creating thumbnails from the file is large or otherwise resource-intensive.

Stability: stable: to override

Parameters

File $file

Returns: bool

Reimplemented in DjVuHandler, and TiffHandler.

Definition at line 1089 of file MediaHandler.php.

Referenced by File\isExpensiveToThumbnail().

◆ isFileMetadataValid()

MediaHandler::isFileMetadataValid ( $image )

Check if the metadata is valid for this handler.

If it returns MediaHandler::METADATA_BAD (or false), Image will reload the metadata from the file and update the database. MediaHandler::METADATA_GOOD for if the metadata is a-ok, MediaHandler::METADATA_COMPATIBLE if metadata is old but backwards compatible (which may or may not trigger a metadata reload).

Note: Returning self::METADATA_BAD will trigger a metadata reload from file on page view. Always returning this from a broken file, or suddenly triggering as bad metadata for a large number of files can cause performance problems.

This was introduced in 1.37 to replace isMetadataValid(), which took a serialized string as a parameter. Handlers overriding this method are expected to use accessors to get the metadata out of the File. The reasons for the change were to get rid of serialization, and to allow handlers to partially load metadata with getMetadataItem(). For example a handler could just validate a version number.

Stability: stable: to override

Since: 1.37

Parameters

File $image

Returns: bool|int

Reimplemented in XCFHandler, DjVuHandler, ExifBitmapHandler, GIFHandler, PNGHandler, SvgHandler, and WebPHandler.

Definition at line 375 of file MediaHandler.php.

References METADATA_GOOD.

Referenced by LocalFile\maybeUpgradeRow().

◆ isMetadataValid()

MediaHandler::isMetadataValid	(		$image,
			$metadata )

Check if the metadata string is valid for this handler.

If it returns MediaHandler::METADATA_BAD (or false), Image will reload the metadata from the file and update the database. MediaHandler::METADATA_GOOD for if the metadata is a-ok, MediaHandler::METADATA_COMPATIBLE if metadata is old but backwards compatible (which may or may not trigger a metadata reload).

Note: Returning self::METADATA_BAD will trigger a metadata reload from file on page view. Always returning this from a broken file, or suddenly triggering as bad metadata for a large number of files can cause performance problems.

Deprecated: since 1.37 use isFileMetadataValid

Parameters

File	$image
string	$metadata	The metadata in serialized form

Returns: bool|int

Definition at line 346 of file MediaHandler.php.

References METADATA_GOOD.

◆ isMultiPage()

MediaHandler::isMultiPage ( $file )

True if the type has multi-page capabilities.

Stability: stable: to override

Parameters

File $file

Returns: bool

Reimplemented in DjVuHandler.

Definition at line 527 of file MediaHandler.php.

◆ isVectorized()

MediaHandler::isVectorized ( $file )

The material is vectorized and thus scaling is lossless.

Stability: stable: to override

Parameters

File $file

Returns: bool

Reimplemented in SvgHandler.

Definition at line 551 of file MediaHandler.php.

Referenced by File\isVectorized().

◆ logErrorForExternalProcess()

MediaHandler::logErrorForExternalProcess	(	$retval,
		$err,
		$cmd )

protected

Log an error that occurred in an external process.

Moved from BitmapHandler to MediaHandler with MediaWiki 1.23

Since: 1.23

Parameters

int	$retval
string	$err	Error reported by command. Anything longer than MediaHandler::MAX_ERR_LOG_SIZE is stripped off.
string	$cmd

Definition at line 1010 of file MediaHandler.php.

References wfDebugLog(), and wfHostname().

Referenced by DjVuHandler\doTransform(), SvgHandler\rasterize(), BitmapHandler\rotate(), JpegHandler\rotate(), JpegHandler\swapICCProfile(), BitmapHandler\transformCustom(), and BitmapHandler\transformImageMagick().

◆ makeParamString()

MediaHandler::makeParamString ( $params )

abstract

Merge a parameter array into a string appropriate for inclusion in filenames.

Parameters

array $params Array of parameters that have been through normaliseParams.

Returns: string

Reimplemented in BitmapHandler, DjVuHandler, ImageHandler, JpegHandler, and SvgHandler.

◆ mustRender()

MediaHandler::mustRender ( $file )

True if handled types cannot be displayed directly in a browser but can be rendered.

Stability: stable: to override

Parameters

File $file

Returns: bool

Reimplemented in BmpHandler, DjVuHandler, Jpeg2000Handler, SvgHandler, TiffHandler, TransformationalImageHandler, WebPHandler, and XCFHandler.

Definition at line 515 of file MediaHandler.php.

◆ normaliseParams()

MediaHandler::normaliseParams	(		$image,
		&	$params )

abstract

Changes the parameter array as necessary, ready for transformation.

Should be idempotent. Returns false if the parameters are unacceptable and the transform should fail

Parameters

File	$image
array	&$params

Returns: bool

Reimplemented in BitmapHandler, BitmapHandler_ClientOnly, ImageHandler, JpegHandler, SvgHandler, and TransformationalImageHandler.

Referenced by File\generateAndSaveThumb(), and File\transform().

◆ pageCount()

MediaHandler::pageCount ( File $file )

Page count for a multi-page document, false if unsupported or unknown.

Stability: stable: to override

Parameters

File $file

Returns: int|false

Reimplemented in DjVuHandler.

Definition at line 539 of file MediaHandler.php.

◆ parseParamString()

MediaHandler::parseParamString ( $str )

abstract

Parse a param string made with makeParamString back into an array.

Parameters

string $str The parameter string without file name (e.g. 122px)

Returns: array|false Array of parameters or false on failure.

Reimplemented in BitmapHandler, DjVuHandler, ImageHandler, JpegHandler, and SvgHandler.

◆ parserTransformHook()

MediaHandler::parserTransformHook	(		$parser,
			$file )

Modify the parser object post-transform.

This is often used to do $parser->addOutputHook(), in order to add some javascript to render a viewer. See TimedMediaHandler or OggHandler for an example.

Stability: stable: to override

Parameters

Parser	$parser
File	$file

Definition at line 898 of file MediaHandler.php.

◆ removeBadFile()

MediaHandler::removeBadFile	(		$dstPath,
			$retval = 0 )

Check for zero-sized thumbnails.

These can be generated when no disk space is available or some other error occurs

Stability: stable: to override

Parameters

string	$dstPath	The location of the suspect file
int	$retval	Return value of some shell process, file will be deleted if this is non-zero

Returns: bool True if removed, false otherwise

Definition at line 927 of file MediaHandler.php.

References wfDebugLog().

Referenced by DjVuHandler\doTransform(), TransformationalImageHandler\doTransform(), and SvgHandler\rasterize().

◆ sanitizeParamsForBucketing()

MediaHandler::sanitizeParamsForBucketing ( $params )

Returns a normalised params array for which parameters have been cleaned up for bucketing purposes.

Stability: stable: to override

Parameters

array $params

Returns: array

Reimplemented in ImageHandler, and JpegHandler.

Definition at line 1113 of file MediaHandler.php.

◆ supportsBucketing()

MediaHandler::supportsBucketing ( )

Returns whether or not this handler supports the chained generation of thumbnails according to buckets.

Stability: stable: to override

Returns: bool

Since: 1.24

Reimplemented in JpegHandler, and PNGHandler.

Definition at line 1101 of file MediaHandler.php.

Referenced by File\generateAndSaveThumb().

◆ useLegacyMetadata()

MediaHandler::useLegacyMetadata ( )

protected

If this returns true, the new method getSizeAndMetadata() will not be called.

The legacy methods getMetadata() and getImageSize() will be used instead.

Since: 1.37

Stability: stable: to override

Returns: bool

Definition at line 180 of file MediaHandler.php.

References hasMostDerivedMethod().

Referenced by getSizeAndMetadataWithFallback().

◆ useSplitMetadata()

MediaHandler::useSplitMetadata ( )

If this returns true, LocalFile may split metadata up and store its constituent items separately.

This only makes sense if the handler calls File::getMetadataItem() or File::getMetadataItems() instead of requesting the whole array at once.

Returns: bool

Reimplemented in DjVuHandler.

Definition at line 1213 of file MediaHandler.php.

◆ validateParam()

MediaHandler::validateParam	(		$name,
			$value )

abstract

Validate a thumbnail parameter at parse time.

Return true to accept the parameter, and false to reject it. If you return false, the parser will do something quiet and forgiving.

Parameters

string	$name
mixed	$value

Returns: bool

Reimplemented in BitmapHandler, DjVuHandler, ImageHandler, JpegHandler, and SvgHandler.

◆ verifyUpload()

MediaHandler::verifyUpload ( $fileName )

File validation hook called on upload.

If the file at the given local path is not valid, or its MIME type does not match the handler class, a Status object should be returned containing relevant errors.

Stability: stable: to override

Parameters

string $fileName The local path to the file.

Returns: Status

Definition at line 913 of file MediaHandler.php.

◆ visibleMetadataFields()

MediaHandler::visibleMetadataFields ( )

protected

Get a list of metadata items which should be displayed when the metadata table is collapsed.

Stability: stable: to override

Returns: string[]

Reimplemented in SvgHandler.

Definition at line 763 of file MediaHandler.php.

References FormatMetadata\getVisibleFields().

Referenced by formatMetadataHelper().

Member Data Documentation

◆ METADATA_BAD

const MediaHandler::METADATA_BAD = false

Definition at line 41 of file MediaHandler.php.

Referenced by XCFHandler\isFileMetadataValid(), DjVuHandler\isFileMetadataValid(), ExifBitmapHandler\isFileMetadataValid(), GIFHandler\isFileMetadataValid(), PNGHandler\isFileMetadataValid(), WebPHandler\isFileMetadataValid(), and LocalFile\maybeUpgradeRow().

◆ METADATA_COMPATIBLE

const MediaHandler::METADATA_COMPATIBLE = 2

Definition at line 42 of file MediaHandler.php.

Referenced by ExifBitmapHandler\isFileMetadataValid(), GIFHandler\isFileMetadataValid(), PNGHandler\isFileMetadataValid(), WebPHandler\isFileMetadataValid(), and LocalFile\maybeUpgradeRow().

◆ METADATA_GOOD

const MediaHandler::METADATA_GOOD = true

Definition at line 40 of file MediaHandler.php.

Referenced by XCFHandler\isFileMetadataValid(), DjVuHandler\isFileMetadataValid(), ExifBitmapHandler\isFileMetadataValid(), GIFHandler\isFileMetadataValid(), isFileMetadataValid(), PNGHandler\isFileMetadataValid(), WebPHandler\isFileMetadataValid(), and isMetadataValid().

◆ TRANSFORM_LATER

const MediaHandler::TRANSFORM_LATER = 1

Definition at line 39 of file MediaHandler.php.

The documentation for this class was generated from the following file:

includes/media/MediaHandler.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Detailed Description

Member Function Documentation

◆ addMeta()

◆ canAnimateThumbnail()

◆ canRender()

◆ canRotate()

◆ convertMetadataVersion()

◆ doTransform()

◆ filterThumbnailPurgeList()

◆ fitBoxWidth()

◆ formatMetadata()

◆ formatMetadataHelper()

◆ formatTag()

◆ getAvailableLanguages()

◆ getCommonMetaArray()

◆ getContentHeaders()

◆ getDefaultRenderLanguage()

◆ getDimensionsString()

◆ getEntireText()

◆ getGeneralLongDesc()

◆ getGeneralShortDesc()

◆ getHandler()

◆ getImageSize()

◆ getLength()

◆ getLongDesc()

◆ getMatchedLanguage()

◆ getMetadata()

◆ getMetadataType()

◆ getMetadataVersion()

◆ getPageDimensions()

◆ getPageRangesByDimensions()

◆ getPageText()

◆ getParamMap()

◆ getRotation()

◆ getScriptedTransform()

◆ getShortDesc()

◆ getSizeAndMetadata()

◆ getSizeAndMetadataWithFallback()

◆ getThumbType()

◆ getTransform()

◆ getWarningConfig()

◆ hasMostDerivedMethod()

◆ isAnimatedImage()

◆ isEnabled()

◆ isExpensiveToThumbnail()

◆ isFileMetadataValid()

◆ isMetadataValid()

◆ isMultiPage()

◆ isVectorized()

◆ logErrorForExternalProcess()

◆ makeParamString()

◆ mustRender()

◆ normaliseParams()

◆ pageCount()

◆ parseParamString()

◆ parserTransformHook()

◆ removeBadFile()

◆ sanitizeParamsForBucketing()

◆ supportsBucketing()

◆ useLegacyMetadata()

◆ useSplitMetadata()

◆ validateParam()

◆ verifyUpload()

◆ visibleMetadataFields()

Member Data Documentation

◆ METADATA_BAD

◆ METADATA_COMPATIBLE

◆ METADATA_GOOD

◆ TRANSFORM_LATER