/**
* Merge a parameter array into a string appropriate for inclusion in filenames
*
- * @param $params array
+ * @param $params array Array of parameters that have been through normaliseParams.
+ * @return String
*/
abstract function makeParamString( $params );
/**
* Parse a param string made with makeParamString back into an array
*
- * @param $str string
+ * @param $str string The parameter string without file name (e.g. 122px)
+ * @return Array|Boolean Array of parameters or false on failure.
*/
abstract function parseParamString( $str );
return self::METADATA_GOOD;
}
+ /**
+ * 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.
+ *
+ * @param File $file
+ *
+ * @return Array or false if interface not supported
+ * @since 1.23
+ */
+ public function getCommonMetaArray( File $file ) {
+ return false;
+ }
+
/**
* Get a MediaTransformOutput object representing an alternate of the transformed
* output which will call an intermediary thumbnail assist script.
* @param string $dstPath filesystem destination path
* @param string $dstUrl destination URL to use in output HTML
* @param array $params arbitrary set of parameters validated by $this->validateParam()
+ * Note: These parameters have *not* gone through $this->normaliseParams()
* @param $flags Integer: a bitfield, may contain self::TRANSFORM_LATER
*
* @return MediaTransformOutput
* 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.
+ * Returns false if unknown.
+ *
+ * It is expected that handlers for paged media (e.g. DjVuHandler)
+ * will override this method so that it gives the correct results
+ * for each specific page of the file, using the $page argument.
+ *
+ * @note For non-paged media, use getImageSize.
*
* @param $image File
- * @param $page Unused, left for backcompatibility?
- * @return array
+ * @param $page What page to get dimensions of
+ * @return array|bool
*/
function getPageDimensions( $image, $page ) {
$gis = $this->getImageSize( $image, $image->getLocalRefPath() );
- return array(
- 'width' => $gis[0],
- 'height' => $gis[1]
- );
+ if ( $gis ) {
+ return array(
+ 'width' => $gis[0],
+ 'height' => $gis[1]
+ );
+ } else {
+ return false;
+ }
}
/**
* @access protected
*/
function visibleMetadataFields() {
- $fields = array();
- $lines = explode( "\n", wfMessage( 'metadata-fields' )->inContentLanguage()->text() );
- foreach ( $lines as $line ) {
- $matches = array();
- if ( preg_match( '/^\\*\s*(.*?)\s*$/', $line, $matches ) ) {
- $fields[] = $matches[1];
- }
- }
- $fields = array_map( 'strtolower', $fields );
- return $fields;
+ return FormatMetadata::getVisibleFields();
}
/**
}
/**
+ * Used instead of getLongDesc if there is no handler registered for file.
+ *
* @param $file File
* @return string
*/
}
/**
+ * Short description. Shown on Special:Search results.
+ *
* @param $file File
* @return string
*/
}
/**
+ * Long description. Shown under image on image description page surounded by ().
+ *
* @param $file File
* @return string
*/
}
/**
+ * Used instead of getShortDesc if there is no handler registered for file.
+ *
* @param $file File
* @return string
*/
}
}
+ /**
+ * Shown in file history box on image description page.
+ *
+ * @param File $file
+ * @return String Dimensions
+ */
function getDimensionsString( $file ) {
return '';
}
/**
- * Modify the parser object post-transform
+ * 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.
+ *
+ * @param Parser $parser
+ * @param File $file
*/
function parserTransformHook( $parser, $file ) {}
}
/**
- * Remove files from the purge list
+ * 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 LocalFile::purgeThumbnails
*
* @param array $files
- * @param array $options
+ * @param array $options Purge options. Currently will always be
+ * an array with a single key 'forThumbRefresh' set to true.
*/
public function filterThumbnailPurgeList( &$files, $options ) {
// Do nothing
public static function canRotate() {
return false;
}
+
+ /**
+ * 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.
+ *
+ * @param $file File
+ * @return int 0, 90, 180 or 270
+ */
+ public function getRotation( $file ) {
+ return 0;
+ }
+
}
dépôts / lhc / web / wiklou.git / blobdiff