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