classes/Kohana/Image.php

   1 <?php defined('SYSPATH') OR die('No direct script access.');
   2 /**
   3  * Image manipulation support. Allows images to be resized, cropped, etc.
   4  *
   5  * @package    Kohana/Image
   6  * @category   Base
   7  * @author     Kohana Team
   8  * @copyright  (c) 2008-2009 Kohana Team
   9  * @license    http://kohanaphp.com/license.html
  10  */
  11 abstract class Kohana_Image {
  12
  13         // Resizing constraints
  14         const NONE    = 0x01;
  15         const WIDTH   = 0x02;
  16         const HEIGHT  = 0x03;
  17         const AUTO    = 0x04;
  18         const INVERSE = 0x05;
  19         const PRECISE = 0x06;
  20
  21         // Flipping directions
  22         const HORIZONTAL = 0x11;
  23         const VERTICAL   = 0x12;
  24
  25         /**
  26          * @var  string  default driver: GD, ImageMagick, etc
  27          */
  28         public static $default_driver = 'GD';
  29
  30         // Status of the driver check
  31         protected static $_checked = FALSE;
  32
  33         /**
  34          * Loads an image and prepares it for manipulation.
  35          *
  36          *     $image = Image::factory('upload/test.jpg');
  37          *
  38          * @param   string   $file    image file path
  39          * @param   string   $driver  driver type: GD, ImageMagick, etc
  40          * @return  Image
  41          * @uses    Image::$default_driver
  42          */
  43         public static function factory($file, $driver = NULL)
  44         {
  45                 if ($driver === NULL)
  46                 {
  47                         // Use the default driver
  48                         $driver = Image::$default_driver;
  49                 }
  50
  51                 // Set the class name
  52                 $class = 'Image_'.$driver;
  53
  54                 return new $class($file);
  55         }
  56
  57         /**
  58          * @var  string  image file path
  59          */
  60         public $file;
  61
  62         /**
  63          * @var  integer  image width
  64          */
  65         public $width;
  66
  67         /**
  68          * @var  integer  image height
  69          */
  70         public $height;
  71
  72         /**
  73          * @var  integer  one of the IMAGETYPE_* constants
  74          */
  75         public $type;
  76
  77         /**
  78          * @var  string  mime type of the image
  79          */
  80         public $mime;
  81
  82         /**
  83          * Loads information about the image. Will throw an exception if the image
  84          * does not exist or is not an image.
  85          *
  86          * @param   string  $file  image file path
  87          * @return  void
  88          * @throws  Kohana_Exception
  89          */
  90         public function __construct($file)
  91         {
  92                 try
  93                 {
  94                         // Get the real path to the file
  95                         $file = realpath($file);
  96
  97                         // Get the image information
  98                         $info = getimagesize($file);
  99                 }
 100                 catch (Exception $e)
 101                 {
 102                         // Ignore all errors while reading the image
 103                 }
 104
 105                 if (empty($file) OR empty($info))
 106                 {
 107                         throw new Kohana_Exception('Not an image or invalid image: :file',
 108                                 array(':file' => Debug::path($file)));
 109                 }
 110
 111                 // Store the image information
 112                 $this->file   = $file;
 113                 $this->width  = $info[0];
 114                 $this->height = $info[1];
 115                 $this->type   = $info[2];
 116                 $this->mime   = image_type_to_mime_type($this->type);
 117         }
 118
 119         /**
 120          * Render the current image.
 121          *
 122          *     echo $image;
 123          *
 124          * [!!] The output of this function is binary and must be rendered with the
 125          * appropriate Content-Type header or it will not be displayed correctly!
 126          *
 127          * @return  string
 128          */
 129         public function __toString()
 130         {
 131                 try
 132                 {
 133                         // Render the current image
 134                         return $this->render();
 135                 }
 136                 catch (Exception $e)
 137                 {
 138                         if (is_object(Kohana::$log))
 139                         {
 140                                 // Get the text of the exception
 141                                 $error = Kohana_Exception::text($e);
 142
 143                                 // Add this exception to the log
 144                                 Kohana::$log->add(Log::ERROR, $error);
 145                         }
 146
 147                         // Showing any kind of error will be "inside" image data
 148                         return '';
 149                 }
 150         }
 151
 152         /**
 153          * Resize the image to the given size. Either the width or the height can
 154          * be omitted and the image will be resized proportionally.
 155          *
 156          *     // Resize to 200 pixels on the shortest side
 157          *     $image->resize(200, 200);
 158          *
 159          *     // Resize to 200x200 pixels, keeping aspect ratio
 160          *     $image->resize(200, 200, Image::INVERSE);
 161          *
 162          *     // Resize to 500 pixel width, keeping aspect ratio
 163          *     $image->resize(500, NULL);
 164          *
 165          *     // Resize to 500 pixel height, keeping aspect ratio
 166          *     $image->resize(NULL, 500);
 167          *
 168          *     // Resize to 200x500 pixels, ignoring aspect ratio
 169          *     $image->resize(200, 500, Image::NONE);
 170          *
 171          * @param   integer  $width   new width
 172          * @param   integer  $height  new height
 173          * @param   integer  $master  master dimension
 174          * @return  $this
 175          * @uses    Image::_do_resize
 176          */
 177         public function resize($width = NULL, $height = NULL, $master = NULL)
 178         {
 179                 if ($master === NULL)
 180                 {
 181                         // Choose the master dimension automatically
 182                         $master = Image::AUTO;
 183                 }
 184                 // Image::WIDTH and Image::HEIGHT deprecated. You can use it in old projects,
 185                 // but in new you must pass empty value for non-master dimension
 186                 elseif ($master == Image::WIDTH AND ! empty($width))
 187                 {
 188                         $master = Image::AUTO;
 189
 190                         // Set empty height for backward compatibility
 191                         $height = NULL;
 192                 }
 193                 elseif ($master == Image::HEIGHT AND ! empty($height))
 194                 {
 195                         $master = Image::AUTO;
 196
 197                         // Set empty width for backward compatibility
 198                         $width = NULL;
 199                 }
 200
 201                 if (empty($width))
 202                 {
 203                         if ($master === Image::NONE)
 204                         {
 205                                 // Use the current width
 206                                 $width = $this->width;
 207                         }
 208                         else
 209                         {
 210                                 // If width not set, master will be height
 211                                 $master = Image::HEIGHT;
 212                         }
 213                 }
 214
 215                 if (empty($height))
 216                 {
 217                         if ($master === Image::NONE)
 218                         {
 219                                 // Use the current height
 220                                 $height = $this->height;
 221                         }
 222                         else
 223                         {
 224                                 // If height not set, master will be width
 225                                 $master = Image::WIDTH;
 226                         }
 227                 }
 228
 229                 switch ($master)
 230                 {
 231                         case Image::AUTO:
 232                                 // Choose direction with the greatest reduction ratio
 233                                 $master = ($this->width / $width) > ($this->height / $height) ? Image::WIDTH : Image::HEIGHT;
 234                         break;
 235                         case Image::INVERSE:
 236                                 // Choose direction with the minimum reduction ratio
 237                                 $master = ($this->width / $width) > ($this->height / $height) ? Image::HEIGHT : Image::WIDTH;
 238                         break;
 239                 }
 240
 241                 switch ($master)
 242                 {
 243                         case Image::WIDTH:
 244                                 // Recalculate the height based on the width proportions
 245                                 $height = $this->height * $width / $this->width;
 246                         break;
 247                         case Image::HEIGHT:
 248                                 // Recalculate the width based on the height proportions
 249                                 $width = $this->width * $height / $this->height;
 250                         break;
 251                         case Image::PRECISE:
 252                                 // Resize to precise size
 253                                 $ratio = $this->width / $this->height;
 254
 255                                 if ($width / $height > $ratio)
 256                                 {
 257                                         $height = $this->height * $width / $this->width;
 258                                 }
 259                                 else
 260                                 {
 261                                         $width = $this->width * $height / $this->height;
 262                                 }
 263                         break;
 264                 }
 265
 266                 // Convert the width and height to integers, minimum value is 1px
 267                 $width  = max(round($width), 1);
 268                 $height = max(round($height), 1);
 269
 270                 $this->_do_resize($width, $height);
 271
 272                 return $this;
 273         }
 274
 275         /**
 276          * Crop an image to the given size. Either the width or the height can be
 277          * omitted and the current width or height will be used.
 278          *
 279          * If no offset is specified, the center of the axis will be used.
 280          * If an offset of TRUE is specified, the bottom of the axis will be used.
 281          *
 282          *     // Crop the image to 200x200 pixels, from the center
 283          *     $image->crop(200, 200);
 284          *
 285          * @param   integer  $width     new width
 286          * @param   integer  $height    new height
 287          * @param   mixed    $offset_x  offset from the left
 288          * @param   mixed    $offset_y  offset from the top
 289          * @return  $this
 290          * @uses    Image::_do_crop
 291          */
 292         public function crop($width, $height, $offset_x = NULL, $offset_y = NULL)
 293         {
 294                 if ($width > $this->width)
 295                 {
 296                         // Use the current width
 297                         $width = $this->width;
 298                 }
 299
 300                 if ($height > $this->height)
 301                 {
 302                         // Use the current height
 303                         $height = $this->height;
 304                 }
 305
 306                 if ($offset_x === NULL)
 307                 {
 308                         // Center the X offset
 309                         $offset_x = round(($this->width - $width) / 2);
 310                 }
 311                 elseif ($offset_x === TRUE)
 312                 {
 313                         // Bottom the X offset
 314                         $offset_x = $this->width - $width;
 315                 }
 316                 elseif ($offset_x < 0)
 317                 {
 318                         // Set the X offset from the right
 319                         $offset_x = $this->width - $width + $offset_x;
 320                 }
 321
 322                 if ($offset_y === NULL)
 323                 {
 324                         // Center the Y offset
 325                         $offset_y = round(($this->height - $height) / 2);
 326                 }
 327                 elseif ($offset_y === TRUE)
 328                 {
 329                         // Bottom the Y offset
 330                         $offset_y = $this->height - $height;
 331                 }
 332                 elseif ($offset_y < 0)
 333                 {
 334                         // Set the Y offset from the bottom
 335                         $offset_y = $this->height - $height + $offset_y;
 336                 }
 337
 338                 // Determine the maximum possible width and height
 339                 $max_width  = $this->width  - $offset_x;
 340                 $max_height = $this->height - $offset_y;
 341
 342                 if ($width > $max_width)
 343                 {
 344                         // Use the maximum available width
 345                         $width = $max_width;
 346                 }
 347
 348                 if ($height > $max_height)
 349                 {
 350                         // Use the maximum available height
 351                         $height = $max_height;
 352                 }
 353
 354                 $this->_do_crop($width, $height, $offset_x, $offset_y);
 355
 356                 return $this;
 357         }
 358
 359         /**
 360          * Rotate the image by a given amount.
 361          *
 362          *     // Rotate 45 degrees clockwise
 363          *     $image->rotate(45);
 364          *
 365          *     // Rotate 90% counter-clockwise
 366          *     $image->rotate(-90);
 367          *
 368          * @param   integer  $degrees  degrees to rotate: -360-360
 369          * @return  $this
 370          * @uses    Image::_do_rotate
 371          */
 372         public function rotate($degrees)
 373         {
 374                 // Make the degrees an integer
 375                 $degrees = (int) $degrees;
 376
 377                 if ($degrees > 180)
 378                 {
 379                         do
 380                         {
 381                                 // Keep subtracting full circles until the degrees have normalized
 382                                 $degrees -= 360;
 383                         }
 384                         while ($degrees > 180);
 385                 }
 386
 387                 if ($degrees < -180)
 388                 {
 389                         do
 390                         {
 391                                 // Keep adding full circles until the degrees have normalized
 392                                 $degrees += 360;
 393                         }
 394                         while ($degrees < -180);
 395                 }
 396
 397                 $this->_do_rotate($degrees);
 398
 399                 return $this;
 400         }
 401
 402         /**
 403          * Flip the image along the horizontal or vertical axis.
 404          *
 405          *     // Flip the image from top to bottom
 406          *     $image->flip(Image::HORIZONTAL);
 407          *
 408          *     // Flip the image from left to right
 409          *     $image->flip(Image::VERTICAL);
 410          *
 411          * @param   integer  $direction  direction: Image::HORIZONTAL, Image::VERTICAL
 412          * @return  $this
 413          * @uses    Image::_do_flip
 414          */
 415         public function flip($direction)
 416         {
 417                 if ($direction !== Image::HORIZONTAL)
 418                 {
 419                         // Flip vertically
 420                         $direction = Image::VERTICAL;
 421                 }
 422
 423                 $this->_do_flip($direction);
 424
 425                 return $this;
 426         }
 427
 428         /**
 429          * Sharpen the image by a given amount.
 430          *
 431          *     // Sharpen the image by 20%
 432          *     $image->sharpen(20);
 433          *
 434          * @param   integer  $amount  amount to sharpen: 1-100
 435          * @return  $this
 436          * @uses    Image::_do_sharpen
 437          */
 438         public function sharpen($amount)
 439         {
 440                 // The amount must be in the range of 1 to 100
 441                 $amount = min(max($amount, 1), 100);
 442
 443                 $this->_do_sharpen($amount);
 444
 445                 return $this;
 446         }
 447
 448         /**
 449          * Add a reflection to an image. The most opaque part of the reflection
 450          * will be equal to the opacity setting and fade out to full transparent.
 451          * Alpha transparency is preserved.
 452          *
 453          *     // Create a 50 pixel reflection that fades from 0-100% opacity
 454          *     $image->reflection(50);
 455          *
 456          *     // Create a 50 pixel reflection that fades from 100-0% opacity
 457          *     $image->reflection(50, 100, TRUE);
 458          *
 459          *     // Create a 50 pixel reflection that fades from 0-60% opacity
 460          *     $image->reflection(50, 60, TRUE);
 461          *
 462          * [!!] By default, the reflection will be go from transparent at the top
 463          * to opaque at the bottom.
 464          *
 465          * @param   integer   $height   reflection height
 466          * @param   integer   $opacity  reflection opacity: 0-100
 467          * @param   boolean   $fade_in  TRUE to fade in, FALSE to fade out
 468          * @return  $this
 469          * @uses    Image::_do_reflection
 470          */
 471         public function reflection($height = NULL, $opacity = 100, $fade_in = FALSE)
 472         {
 473                 if ($height === NULL OR $height > $this->height)
 474                 {
 475                         // Use the current height
 476                         $height = $this->height;
 477                 }
 478
 479                 // The opacity must be in the range of 0 to 100
 480                 $opacity = min(max($opacity, 0), 100);
 481
 482                 $this->_do_reflection($height, $opacity, $fade_in);
 483
 484                 return $this;
 485         }
 486
 487         /**
 488          * Add a watermark to an image with a specified opacity. Alpha transparency
 489          * will be preserved.
 490          *
 491          * If no offset is specified, the center of the axis will be used.
 492          * If an offset of TRUE is specified, the bottom of the axis will be used.
 493          *
 494          *     // Add a watermark to the bottom right of the image
 495          *     $mark = Image::factory('upload/watermark.png');
 496          *     $image->watermark($mark, TRUE, TRUE);
 497          *
 498          * @param   Image    $watermark  watermark Image instance
 499          * @param   integer  $offset_x   offset from the left
 500          * @param   integer  $offset_y   offset from the top
 501          * @param   integer  $opacity    opacity of watermark: 1-100
 502          * @return  $this
 503          * @uses    Image::_do_watermark
 504          */
 505         public function watermark(Image $watermark, $offset_x = NULL, $offset_y = NULL, $opacity = 100)
 506         {
 507                 if ($offset_x === NULL)
 508                 {
 509                         // Center the X offset
 510                         $offset_x = round(($this->width - $watermark->width) / 2);
 511                 }
 512                 elseif ($offset_x === TRUE)
 513                 {
 514                         // Bottom the X offset
 515                         $offset_x = $this->width - $watermark->width;
 516                 }
 517                 elseif ($offset_x < 0)
 518                 {
 519                         // Set the X offset from the right
 520                         $offset_x = $this->width - $watermark->width + $offset_x;
 521                 }
 522
 523                 if ($offset_y === NULL)
 524                 {
 525                         // Center the Y offset
 526                         $offset_y = round(($this->height - $watermark->height) / 2);
 527                 }
 528                 elseif ($offset_y === TRUE)
 529                 {
 530                         // Bottom the Y offset
 531                         $offset_y = $this->height - $watermark->height;
 532                 }
 533                 elseif ($offset_y < 0)
 534                 {
 535                         // Set the Y offset from the bottom
 536                         $offset_y = $this->height - $watermark->height + $offset_y;
 537                 }
 538
 539                 // The opacity must be in the range of 1 to 100
 540                 $opacity = min(max($opacity, 1), 100);
 541
 542                 $this->_do_watermark($watermark, $offset_x, $offset_y, $opacity);
 543
 544                 return $this;
 545         }
 546
 547         /**
 548          * Set the background color of an image. This is only useful for images
 549          * with alpha transparency.
 550          *
 551          *     // Make the image background black
 552          *     $image->background('#000');
 553          *
 554          *     // Make the image background black with 50% opacity
 555          *     $image->background('#000', 50);
 556          *
 557          * @param   string   $color    hexadecimal color value
 558          * @param   integer  $opacity  background opacity: 0-100
 559          * @return  $this
 560          * @uses    Image::_do_background
 561          */
 562         public function background($color, $opacity = 100)
 563         {
 564                 if ($color[0] === '#')
 565                 {
 566                         // Remove the pound
 567                         $color = substr($color, 1);
 568                 }
 569
 570                 if (strlen($color) === 3)
 571                 {
 572                         // Convert shorthand into longhand hex notation
 573                         $color = preg_replace('/./', '$0$0', $color);
 574                 }
 575
 576                 // Convert the hex into RGB values
 577                 list ($r, $g, $b) = array_map('hexdec', str_split($color, 2));
 578
 579                 // The opacity must be in the range of 0 to 100
 580                 $opacity = min(max($opacity, 0), 100);
 581
 582                 $this->_do_background($r, $g, $b, $opacity);
 583
 584                 return $this;
 585         }
 586
 587         /**
 588          * Save the image. If the filename is omitted, the original image will
 589          * be overwritten.
 590          *
 591          *     // Save the image as a PNG
 592          *     $image->save('saved/cool.png');
 593          *
 594          *     // Overwrite the original image
 595          *     $image->save();
 596          *
 597          * [!!] If the file exists, but is not writable, an exception will be thrown.
 598          *
 599          * [!!] If the file does not exist, and the directory is not writable, an
 600          * exception will be thrown.
 601          *
 602          * @param   string   $file     new image path
 603          * @param   integer  $quality  quality of image: 1-100
 604          * @return  boolean
 605          * @uses    Image::_save
 606          * @throws  Kohana_Exception
 607          */
 608         public function save($file = NULL, $quality = 100)
 609         {
 610                 if ($file === NULL)
 611                 {
 612                         // Overwrite the file
 613                         $file = $this->file;
 614                 }
 615
 616                 if (is_file($file))
 617                 {
 618                         if ( ! is_writable($file))
 619                         {
 620                                 throw new Kohana_Exception('File must be writable: :file',
 621                                         array(':file' => Debug::path($file)));
 622                         }
 623                 }
 624                 else
 625                 {
 626                         // Get the directory of the file
 627                         $directory = realpath(pathinfo($file, PATHINFO_DIRNAME));
 628
 629                         if ( ! is_dir($directory) OR ! is_writable($directory))
 630                         {
 631                                 throw new Kohana_Exception('Directory must be writable: :directory',
 632                                         array(':directory' => Debug::path($directory)));
 633                         }
 634                 }
 635
 636                 // The quality must be in the range of 1 to 100
 637                 $quality = min(max($quality, 1), 100);
 638
 639                 return $this->_do_save($file, $quality);
 640         }
 641
 642         /**
 643          * Render the image and return the binary string.
 644          *
 645          *     // Render the image at 50% quality
 646          *     $data = $image->render(NULL, 50);
 647          *
 648          *     // Render the image as a PNG
 649          *     $data = $image->render('png');
 650          *
 651          * @param   string   $type     image type to return: png, jpg, gif, etc
 652          * @param   integer  $quality  quality of image: 1-100
 653          * @return  string
 654          * @uses    Image::_do_render
 655          */
 656         public function render($type = NULL, $quality = 100)
 657         {
 658                 if ($type === NULL)
 659                 {
 660                         // Use the current image type
 661                         $type = image_type_to_extension($this->type, FALSE);
 662                 }
 663
 664                 return $this->_do_render($type, $quality);
 665         }
 666
 667         /**
 668          * Execute a resize.
 669          *
 670          * @param   integer  $width   new width
 671          * @param   integer  $height  new height
 672          * @return  void
 673          */
 674         abstract protected function _do_resize($width, $height);
 675
 676         /**
 677          * Execute a crop.
 678          *
 679          * @param   integer  $width     new width
 680          * @param   integer  $height    new height
 681          * @param   integer  $offset_x  offset from the left
 682          * @param   integer  $offset_y  offset from the top
 683          * @return  void
 684          */
 685         abstract protected function _do_crop($width, $height, $offset_x, $offset_y);
 686
 687         /**
 688          * Execute a rotation.
 689          *
 690          * @param   integer  $degrees  degrees to rotate
 691          * @return  void
 692          */
 693         abstract protected function _do_rotate($degrees);
 694
 695         /**
 696          * Execute a flip.
 697          *
 698          * @param   integer  $direction  direction to flip
 699          * @return  void
 700          */
 701         abstract protected function _do_flip($direction);
 702
 703         /**
 704          * Execute a sharpen.
 705          *
 706          * @param   integer  $amount  amount to sharpen
 707          * @return  void
 708          */
 709         abstract protected function _do_sharpen($amount);
 710
 711         /**
 712          * Execute a reflection.
 713          *
 714          * @param   integer   $height   reflection height
 715          * @param   integer   $opacity  reflection opacity
 716          * @param   boolean   $fade_in  TRUE to fade out, FALSE to fade in
 717          * @return  void
 718          */
 719         abstract protected function _do_reflection($height, $opacity, $fade_in);
 720
 721         /**
 722          * Execute a watermarking.
 723          *
 724          * @param   Image    $image     watermarking Image
 725          * @param   integer  $offset_x  offset from the left
 726          * @param   integer  $offset_y  offset from the top
 727          * @param   integer  $opacity   opacity of watermark
 728          * @return  void
 729          */
 730         abstract protected function _do_watermark(Image $image, $offset_x, $offset_y, $opacity);
 731
 732         /**
 733          * Execute a background.
 734          *
 735          * @param   integer  $r        red
 736          * @param   integer  $g        green
 737          * @param   integer  $b        blue
 738          * @param   integer  $opacity  opacity
 739          * @return void
 740          */
 741         abstract protected function _do_background($r, $g, $b, $opacity);
 742
 743         /**
 744          * Execute a save.
 745          *
 746          * @param   string   $file     new image filename
 747          * @param   integer  $quality  quality
 748          * @return  boolean
 749          */
 750         abstract protected function _do_save($file, $quality);
 751
 752         /**
 753          * Execute a render.
 754          *
 755          * @param   string    $type     image type: png, jpg, gif, etc
 756          * @param   integer   $quality  quality
 757          * @return  string
 758          */
 759         abstract protected function _do_render($type, $quality);
 760
 761 } // End Image