includes/media/Generic.php

   1 <?php
   2
   3 /**
   4  * Media-handling base classes and generic functionality
   5  */
   6
   7 /**
   8  * Base media handler class
   9  */
  10 abstract class MediaHandler {
  11         const TRANSFORM_LATER = 1;
  12
  13         /**
  14          * Instance cache
  15          */
  16         static $handlers = array();
  17
  18         /**
  19          * Get a MediaHandler for a given MIME type from the instance cache
  20          */
  21         static function getHandler( $type ) {
  22                 global $wgMediaHandlers;
  23                 if ( !isset( $wgMediaHandlers[$type] ) ) {
  24                         wfDebug( __METHOD__ . ": no handler found for $type.\n");
  25                         return false;
  26                 }
  27                 $class = $wgMediaHandlers[$type];
  28                 if ( !isset( self::$handlers[$class] ) ) {
  29                         self::$handlers[$class] = new $class;
  30                         if ( !self::$handlers[$class]->isEnabled() ) {
  31                                 self::$handlers[$class] = false;
  32                         }
  33                 }
  34                 return self::$handlers[$class];
  35         }
  36
  37         /*
  38          * Validate a thumbnail parameter at parse time.
  39          * Return true to accept the parameter, and false to reject it.
  40          * If you return false, the parser will do something quiet and forgiving.
  41          */
  42         abstract function validateParam( $name, $value );
  43
  44         /**
  45          * Merge a parameter array into a string appropriate for inclusion in filenames
  46          */
  47         abstract function makeParamString( $params );
  48
  49         /**
  50          * Parse a param string made with makeParamString back into an array
  51          */
  52         abstract function parseParamString( $str );
  53
  54         /**
  55          * Changes the parameter array as necessary, ready for transformation.
  56          * Should be idempotent.
  57          * Returns false if the parameters are unacceptable and the transform should fail
  58          */
  59         abstract function normaliseParams( $image, &$params );
  60
  61         /**
  62          * Get an image size array like that returned by getimagesize(), or false if it
  63          * can't be determined.
  64          *
  65          * @param Image $image The image object, or false if there isn't one
  66          * @param string $fileName The filename
  67          * @return array
  68          */
  69         abstract function getImageSize( $image, $path );
  70
  71         /**
  72          * Get handler-specific metadata which will be saved in the img_metadata field.
  73          *
  74          * @param Image $image The image object, or false if there isn't one
  75          * @param string $fileName The filename
  76          * @return string
  77          */
  78         function getMetadata( $image, $path ) { return ''; }
  79
  80         /**
  81          * Get a string describing the type of metadata, for display purposes.
  82          */
  83         function getMetadataType( $image ) { return false; }
  84
  85         /**
  86          * Check if the metadata string is valid for this handler.
  87          * If it returns false, Image will reload the metadata from the file and update the database
  88          */
  89         function isMetadataValid( $image, $metadata ) { return true; }
  90
  91         /**
  92          * Get a MediaTransformOutput object representing the transformed output. Does not
  93          * actually do the transform.
  94          *
  95          * @param Image $image The image object
  96          * @param string $dstPath Filesystem destination path
  97          * @param string $dstUrl Destination URL to use in output HTML
  98          * @param array $params Arbitrary set of parameters validated by $this->validateParam()
  99          */
 100         function getTransform( $image, $dstPath, $dstUrl, $params ) {
 101                 return $this->doTransform( $image, $dstPath, $dstUrl, $params, self::TRANSFORM_LATER );
 102         }
 103
 104         /**
 105          * Get a MediaTransformOutput object representing the transformed output. Does the
 106          * transform unless $flags contains self::TRANSFORM_LATER.
 107          *
 108          * @param Image $image The image object
 109          * @param string $dstPath Filesystem destination path
 110          * @param string $dstUrl Destination URL to use in output HTML
 111          * @param array $params Arbitrary set of parameters validated by $this->validateParam()
 112          * @param integer $flags A bitfield, may contain self::TRANSFORM_LATER
 113          */
 114         abstract function doTransform( $image, $dstPath, $dstUrl, $params, $flags = 0 );
 115
 116         /**
 117          * Get the thumbnail extension and MIME type for a given source MIME type
 118          * @return array thumbnail extension and MIME type
 119          */
 120         function getThumbType( $ext, $mime ) {
 121                 return array( $ext, $mime );
 122         }
 123
 124         /**
 125          * True if the handled types can be transformed
 126          */
 127         function canRender() { return true; }
 128         /**
 129          * True if handled types cannot be displayed directly in a browser
 130          * but can be rendered
 131          */
 132         function mustRender() { return false; }
 133         /**
 134          * True if the type has multi-page capabilities
 135          */
 136         function isMultiPage() { return false; }
 137         /**
 138          * Page count for a multi-page document, false if unsupported or unknown
 139          */
 140         function pageCount() { return false; }
 141         /**
 142          * False if the handler is disabled for all files
 143          */
 144         function isEnabled() { return true; }
 145
 146         /**
 147          * Get an associative array of page dimensions
 148          * Currently "width" and "height" are understood, but this might be
 149          * expanded in the future.
 150          * Returns false if unknown or if the document is not multi-page.
 151          */
 152         function getPageDimensions( $image, $page ) {
 153                 $gis = $this->getImageSize( $image, $image->getImagePath() );
 154                 return array(
 155                         'width' => $gis[0],
 156                         'height' => $gis[1]
 157                 );
 158         }
 159 }
 160
 161 /**
 162  * Media handler abstract base class for images
 163  */
 164 abstract class ImageHandler extends MediaHandler {
 165         function validateParam( $name, $value ) {
 166                 if ( in_array( $name, array( 'width', 'height' ) ) ) {
 167                         if ( $value <= 0 ) {
 168                                 return false;
 169                         } else {
 170                                 return true;
 171                         }
 172                 } else {
 173                         return false;
 174                 }
 175         }
 176
 177         function makeParamString( $params ) {
 178                 if ( isset( $params['physicalWidth'] ) ) {
 179                         $width = $params['physicalWidth'];
 180                 } else {
 181                         $width = $params['width'];
 182                 }
 183                 $width = intval( $width );
 184                 return "{$width}px";
 185         }
 186
 187         function parseParamString( $str ) {
 188                 $m = false;
 189                 if ( preg_match( '/^(\d+)px$/', $str, $m ) ) {
 190                         return array( 'width' => $m[1] );
 191                 } else {
 192                         return false;
 193                 }
 194         }
 195
 196         function getScriptParams( $params ) {
 197                 return array( 'width' => $params['width'] );
 198         }
 199
 200         function normaliseParams( $image, &$params ) {
 201                 $mimeType = $image->getMimeType();
 202
 203                 if ( !isset( $params['width'] ) ) {
 204                         return false;
 205                 }
 206                 if ( !isset( $params['page'] ) ) {
 207                         $params['page'] = 1;
 208                 }
 209                 $srcWidth = $image->getWidth( $params['page'] );
 210                 $srcHeight = $image->getHeight( $params['page'] );
 211                 if ( isset( $params['height'] ) && $params['height'] != -1 ) {
 212                         if ( $params['width'] * $srcHeight > $params['height'] * $srcWidth ) {
 213                                 $params['width'] = wfFitBoxWidth( $srcWidth, $srcHeight, $params['height'] );
 214                         }
 215                 }
 216                 $params['height'] = Image::scaleHeight( $srcWidth, $srcHeight, $params['width'] );
 217                 if ( !$this->validateThumbParams( $params['width'], $params['height'], $srcWidth, $srcHeight, $mimeType ) ) {
 218                         return false;
 219                 }
 220                 return true;
 221         }
 222
 223         /**
 224          * Get a transform output object without actually doing the transform
 225          */
 226         function getTransform( $image, $dstPath, $dstUrl, $params ) {
 227                 return $this->doTransform( $image, $dstPath, $dstUrl, $params, self::TRANSFORM_LATER );
 228         }
 229
 230         /**
 231          * Validate thumbnail parameters and fill in the correct height
 232          *
 233          * @param integer &$width Specified width (input/output)
 234          * @param integer &$height Height (output only)
 235          * @return false to indicate that an error should be returned to the user.
 236          */
 237         function validateThumbParams( &$width, &$height, $srcWidth, $srcHeight, $mimeType ) {
 238                 $width = intval( $width );
 239
 240                 # Sanity check $width
 241                 if( $width <= 0) {
 242                         wfDebug( __METHOD__.": Invalid destination width: $width\n" );
 243                         return false;
 244                 }
 245                 if ( $srcWidth <= 0 ) {
 246                         wfDebug( __METHOD__.": Invalid source width: $srcWidth\n" );
 247                         return false;
 248                 }
 249
 250                 $height = Image::scaleHeight( $srcWidth, $srcHeight, $width );
 251                 return true;
 252         }
 253
 254         function getScriptedTransform( $image, $script, $params ) {
 255                 if ( !$this->normaliseParams( $image, $params ) ) {
 256                         return false;
 257                 }
 258                 $url = $script . '&' . wfArrayToCGI( $this->getScriptParams( $params ) );
 259                 return new ThumbnailImage( $url, $params['width'], $params['height'] );
 260         }
 261
 262         /**
 263          * Check for zero-sized thumbnails. These can be generated when
 264          * no disk space is available or some other error occurs
 265          *
 266          * @param $dstPath The location of the suspect file
 267          * @param $retval Return value of some shell process, file will be deleted if this is non-zero
 268          * @return true if removed, false otherwise
 269          */
 270         function removeBadFile( $dstPath, $retval = 0 ) {
 271                 $removed = false;
 272                 if( file_exists( $dstPath ) ) {
 273                         $thumbstat = stat( $dstPath );
 274                         if( $thumbstat['size'] == 0 || $retval != 0 ) {
 275                                 wfDebugLog( 'thumbnail',
 276                                         sprintf( 'Removing bad %d-byte thumbnail "%s"',
 277                                                 $thumbstat['size'], $dstPath ) );
 278                                 unlink( $dstPath );
 279                                 return true;
 280                         }
 281                 }
 282                 return false;
 283         }
 284
 285         function getImageSize( $image, $path ) {
 286                 wfSuppressWarnings();
 287                 $gis = getimagesize( $path );
 288                 wfRestoreWarnings();
 289                 return $gis;
 290         }
 291 }
 292
 293 ?>