Base media handler class. More...

Inheritance diagram for MediaHandler:

Public Member Functions
	canRender ($file)
	True if the handled types can be transformed.
	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)
	Get an array structure that looks like this:
	formatMetadataHelper ($metadataArray)
	sorts the visible/invisible field.
	getDimensionsString ($file)
	getImageSize ($image, $path)
	Get an image size array like that returned by getimagesize(), or false if it can't be determined.
	getLongDesc ($file)
	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 ($image, $page)
	Get an associative array of page dimensions Currently "width" and "height" are understood, but this might be expanded in the future.
	getPageText ($image, $page)
	Generic getter for text layer.
	getParamMap ()
	Get an associative array mapping magic word IDs to parameter names.
	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)
	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.
	isEnabled ()
	False if the handler is disabled for all files.
	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)
	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.
	validateParam ($name, $value)
	Validate a thumbnail parameter at parse time.
	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 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)
static	getGeneralShortDesc ($file)
static	getHandler ($type)
	Get a MediaHandler for a given MIME type from the instance cache.
static	getMetadataVersion ()
	Get metadata version.
Public Attributes
const	METADATA_BAD = false
const	METADATA_COMPATIBLE = 2
const	METADATA_GOOD = true
const	TRANSFORM_LATER = 1
Static Public Attributes
static	$handlers = array()
	Instance cache.
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.

Definition at line 14 of file Generic.php.

Member Function Documentation

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

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.
$visibility	string ('visible' or 'collapsed') if this value is hidden by default.
$type	String type of metadata tag (currently always 'exif')
$id	String the name of the metadata tag (like 'artist' for example). its name in the table displayed is the message "$type-$id" (Ex exif-artist ).
$value	String 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.
$param	String 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 382 of file Generic.php.

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

Referenced by SvgHandler\formatMetadata(), and formatMetadataHelper().

Here is the call graph for this function:

Here is the caller graph for this function:

MediaHandler::canRender ( $ file )

True if the handled types can be transformed.

Reimplemented in ImageHandler, and TiffHandler.

Definition at line 231 of file Generic.php.

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.

Parameters:

$metadata	Mixed String or Array metadata array (serialized if string)
$version	Integer target version

Returns:: Array serialized metadata in specified version, or $metadata on fail.

Reimplemented in ExifBitmapHandler.

Definition at line 137 of file Generic.php.

References wfRestoreWarnings(), and wfSuppressWarnings().

Here is the call graph for this function:

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.

Parameters:

$image	File: the image object
$dstPath	String: filesystem destination path
$dstUrl	String: destination URL to use in output HTML
$params	Array: arbitrary set of parameters validated by $this->validateParam()
$flags	Integer: a bitfield, may contain self::TRANSFORM_LATER

Returns:: MediaTransformOutput

Reimplemented in DjVuHandler, BitmapHandler, SvgHandler, and BitmapHandler_ClientOnly.

Referenced by getTransform().

Here is the caller graph for this function:

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

Remove files from the purge list.

Parameters:

array	$files
array	$options

Definition at line 516 of file Generic.php.

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:

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

Returns:: Integer.

Definition at line 448 of file Generic.php.

Referenced by ImageHandler\normaliseParams(), and MediaHandlerTest\testFitBoxWidth().

Here is the caller graph for this function:

MediaHandler::formatMetadata ( $ image )

Get an array structure that looks like this:

array( 'visible' => array( 'Human-readable name' => 'Human readable value', ... ), 'collapsed' => array( '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: I don't really like this interface, it's not very flexible I think 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.

Reimplemented in SvgHandler, ExifBitmapHandler, PNGHandler, and GIFHandler.

Definition at line 304 of file Generic.php.

MediaHandler::formatMetadataHelper ( $ metadataArray )

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

Parameters:

$metadataArray Array metadata array

Returns:: array for use displaying metadata.

Definition at line 317 of file Generic.php.

References $result, addMeta(), FormatMetadata\getFormattedData(), and visibleMetadataFields().

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

Here is the call graph for this function:

Here is the caller graph for this function:

MediaHandler::getDimensionsString ( $ file )

Reimplemented in ImageHandler.

Definition at line 458 of file Generic.php.

static MediaHandler::getGeneralLongDesc ( $ file ) [static]

Parameters:

$file File

Returns:: string

Definition at line 434 of file Generic.php.

References $file, $wgLang, and wfMessage().

Referenced by File\getLongDesc().

Here is the call graph for this function:

Here is the caller graph for this function:

static MediaHandler::getGeneralShortDesc ( $ file ) [static]

Parameters:

$file File

Returns:: string

Definition at line 425 of file Generic.php.

References $file, and $wgLang.

Referenced by File\getShortDesc().

Here is the caller graph for this function:

static MediaHandler::getHandler ( $ type ) [static]

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

Parameters:

$type string

Returns:: MediaHandler

Definition at line 31 of file Generic.php.

References $wgMediaHandlers, isEnabled(), and wfDebug().

Referenced by FSFile\getProps(), and UploadBase\verifyFile().

Here is the call graph for this function:

Here is the caller graph for this function:

MediaHandler::getImageSize	(	$	image,
		$	path
	)		`[abstract]`

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

Parameters:

$image	File: the image object, or false if there isn't one
$path	String: the filename

Returns:: Array Follow the format of PHP getimagesize() internal function. See http://www.php.net/getimagesize

Reimplemented in ImageHandler, DjVuHandler, ExifBitmapHandler, XCFHandler, and BmpHandler.

Referenced by getPageDimensions().

Here is the caller graph for this function:

MediaHandler::getLongDesc ( $ file )

Parameters:

$file File

Returns:: string

Reimplemented in ImageHandler, SvgHandler, GIFHandler, and PNGHandler.

Definition at line 415 of file Generic.php.

References $file, $wgLang, and wfMessage().

Here is the call graph for this function:

MediaHandler::getMetadata	(	$	image,
		$	path
	)

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

Parameters:

$image	File: the image object, or false if there isn't one. Warning, FSFile::getPropsFromPath might pass an (object)array() instead (!)
$path	String: the filename

Returns:: String

Reimplemented in DjVuHandler, SvgHandler, TiffHandler, PNGHandler, GIFHandler, and JpegHandler.

Definition at line 104 of file Generic.php.

Referenced by ExifBitmapHandler\getImageSize().

Here is the caller graph for this function:

MediaHandler::getMetadataType ( $ image )

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

Returns:: string

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

Definition at line 154 of file Generic.php.

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 ForiegnApiRepo 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'.

Returns:: string version string

Definition at line 121 of file Generic.php.

References $version, and wfRunHooks().

Referenced by ForeignAPIFile\newFromTitle().

Here is the call graph for this function:

Here is the caller graph for this function:

MediaHandler::getPageDimensions	(	$	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 or if the document is not multi-page.

Parameters:

$image File

Reimplemented in DjVuHandler.

Definition at line 262 of file Generic.php.

References getImageSize().

Here is the call graph for this function:

MediaHandler::getPageText	(	$	image,
		$	page
	)

Generic getter for text layer.

Currently overloaded by PDF and DjVu handlers

Reimplemented in DjVuHandler.

Definition at line 274 of file Generic.php.

MediaHandler::getParamMap ( ) [abstract]

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

Will be used by the parser to identify parameters.

Reimplemented in ImageHandler, and DjVuHandler.

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().

Reimplemented in ImageHandler.

Definition at line 177 of file Generic.php.

MediaHandler::getShortDesc ( $ file )

Parameters:

$file File

Returns:: string

Reimplemented in ImageHandler.

Definition at line 406 of file Generic.php.

References $file, and $wgLang.

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

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

Returns:: array thumbnail extension and MIME type

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

Definition at line 212 of file Generic.php.

References $ext, $extensions, $mime, false, and MimeMagic\singleton().

Here is the call graph for this function:

MediaHandler::getTransform	(	$	image,
		$	dstPath,
		$	dstUrl,
		$	params
	)		`[final]`

Get a MediaTransformOutput object representing the transformed output.

Does not actually do the transform.

Parameters:

$image	File: the image object
$dstPath	String: filesystem destination path
$dstUrl	String: Destination URL to use in output HTML
$params	Array: Arbitrary set of parameters validated by $this->validateParam()

Definition at line 190 of file Generic.php.

References doTransform().

Here is the call graph for this function:

MediaHandler::isEnabled ( )

False if the handler is disabled for all files.

Reimplemented in DjVuHandler, and SvgHandler.

Definition at line 252 of file Generic.php.

Referenced by getHandler().

Here is the caller graph for this function:

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, MediaHanlder::METADATA_COMPATIBLE if metadata is old but backwards compatible (which may or may not trigger a metadata reload).

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

Definition at line 164 of file Generic.php.

References METADATA_GOOD.

MediaHandler::isMultiPage ( $ file )

True if the type has multi-page capabilities.

Reimplemented in DjVuHandler.

Definition at line 240 of file Generic.php.

MediaHandler::isVectorized ( $ file )

The material is vectorized and thus scaling is lossless.

Reimplemented in SvgHandler.

Definition at line 248 of file Generic.php.

MediaHandler::makeParamString ( $ params ) [abstract]

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

Parameters:

$params array

Reimplemented in ImageHandler, and DjVuHandler.

MediaHandler::mustRender ( $ file )

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

Reimplemented in BitmapHandler, TiffHandler, DjVuHandler, SvgHandler, XCFHandler, and BmpHandler.

Definition at line 236 of file Generic.php.

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:

$image
$params

Reimplemented in ImageHandler, SvgHandler, BitmapHandler_ClientOnly, and BitmapHandler.

MediaHandler::pageCount ( $ file )

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

Reimplemented in DjVuHandler.

Definition at line 244 of file Generic.php.

MediaHandler::parseParamString ( $ str ) [abstract]

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

Parameters:

$str string

Reimplemented in ImageHandler, and DjVuHandler.

MediaHandler::parserTransformHook	(	$	parser,
		$	file
	)

Modify the parser object post-transform.

Definition at line 465 of file Generic.php.

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

Parameters:

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

Returns:: true if removed, false otherwise

Definition at line 489 of file Generic.php.

References $result, and wfDebugLog().

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

Here is the call graph for this function:

Here is the caller graph for this function:

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:

$name
$value

Reimplemented in ImageHandler, and DjVuHandler.

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.

Parameters:

$fileName The local path to the file.