classes/kohana/image.php

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