X-Git-Url: https://git.heureux-cyclage.org/?a=blobdiff_plain;f=includes%2Fmedia%2FMediaHandler.php;h=ddb8efd7d1f14a14e7e25f40a4f0c6e415132612;hb=657a337d5b4c2f0654fd3927b1799ae0478dbd15;hp=fd576e02825cd466e86cb94d0f1a82149bb45475;hpb=48b05fa86060db3192623655ec38dbe3ce7b9f91;p=lhc%2Fweb%2Fwiklou.git

diff --git a/includes/media/MediaHandler.php b/includes/media/MediaHandler.php
old mode 100644
new mode 100755
index fd576e0282..ddb8efd7d1
--- a/includes/media/MediaHandler.php
+++ b/includes/media/MediaHandler.php
@@ -78,14 +78,16 @@ abstract class MediaHandler {
 	/**
 	 * 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 );
 
@@ -185,6 +187,43 @@ abstract class MediaHandler {
 		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.
@@ -220,6 +259,7 @@ abstract class MediaHandler {
 	 * @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
@@ -331,18 +371,28 @@ abstract class MediaHandler {
 	 * 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;
+		}
 	}
 
 	/**
@@ -423,16 +473,7 @@ abstract class MediaHandler {
 	 * @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();
 	}
 
 	/**
@@ -479,6 +520,8 @@ abstract class MediaHandler {
 	}
 
 	/**
+	 * Used instead of getLongDesc if there is no handler registered for file.
+	 *
 	 * @param $file File
 	 * @return string
 	 */
@@ -488,6 +531,8 @@ abstract class MediaHandler {
 	}
 
 	/**
+	 * Short description. Shown on Special:Search results.
+	 *
 	 * @param $file File
 	 * @return string
 	 */
@@ -498,6 +543,8 @@ abstract class MediaHandler {
 	}
 
 	/**
+	 * Long description. Shown under image on image description page surounded by ().
+	 *
 	 * @param $file File
 	 * @return string
 	 */
@@ -507,6 +554,8 @@ abstract class MediaHandler {
 	}
 
 	/**
+	 * Used instead of getShortDesc if there is no handler registered for file.
+	 *
 	 * @param $file File
 	 * @return string
 	 */
@@ -534,12 +583,25 @@ abstract class MediaHandler {
 		}
 	}
 
+	/**
+	 * 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 ) {}
 
@@ -587,10 +649,17 @@ abstract class MediaHandler {
 	}
 
 	/**
-	 * 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
@@ -604,4 +673,23 @@ abstract class MediaHandler {
 	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;
+	}
+
 }