This is documentation for Kohana v2.3.x.
| Status | Final Draft |
|---|---|
| Todo | Proofread |
Provides methods for the dynamic manipulation of images. Various image formats such as JPEG, PNG, and GIF can be resized, cropped, rotated and sharpened.
All image manipulations are applied to a temporary image. Only the save() method is permanent, the temporary image being written to a specified image file.
Image manipulation methods can be chained efficiently. Recommended order: resize, crop, sharpen, quality and rotate or flip
Uses a driver, configured in config/image.php. The default driver uses the GD2 library, bundled with PHP. ImageMagick may be used if available.
When loading the library, a path to the image file, (relative or absolute) must be passed as a parameter.
Load the Image Library in your controller using the new keyword:
$this->image = new Image('./photo.jpg');
Access to the library is available through $this→image Some methods are chainable.
To change default settings, edit application/config/image.php
Drivers available:
sharpen may not be available)$config['driver'] = 'GD'; // For Windows $config['params'] = array('directory' => 'C:/ImageMagick'); // For Un*x assuming the binary is in usr/local/bin $config['params'] = array('directory' => '/usr/local/bin');
resize() is used to resize an image. This method is chainable. By default, the aspect ratio will be maintained automatically.
Example:
// Resize original image to width of 400 and height of 200 pixels without maintaining the aspect ratio. $this->image->resize(400, 200, Image::NONE) //Note: The output image is resized to width of 400 and height of 200, without maintaining the aspect ratio // Resize original image to Height of 200 pixels, using height to maintain aspect ratio. $this->image->resize(400, 200, Image::HEIGHT) // Note: Passing width = 400 has no effect on the resized width, which is controlled by the 3rd argument, maintain aspect ratio on height // Resize original image (800x600) using automatic aspect ratio calculation $this->image->resize(740,400,Image::AUTO) // the resulting resized image is 533x400 because Kohana determines the master dimension to be height 800/740 < 600/400
crop() is used to crop an image to a specific width and height. This method is chainable.
The top and left offsets may be specified. By default 'top' and 'left' use the 'center' offset.
Example:
// Crop from the original image, starting from the 'center' of the image from the 'top' and the 'center' of the image from the 'left' // to a width of 400 and height of 350. $this->image->crop(400, 350)
rotate() is used to rotate an image by a specified number of degrees. This method is chainable. The image may be rotated clockwise or anti-clockwise, by a maximum of 180 degrees.
Example:
// Rotate the image by 45 degrees to the 'left' or anti-clockwise. $this->image->rotate(-45)
flip() is used to rotate an image along the horizontal or vertical axis. The method is chainable.
Example:
// Rotate the image along the vertical access. $this->image->flip(6);
sharpen() Is used to sharpen an image by a specified amount. This method is chainable.
Example:
// Sharpen the image by an amount of 15. $this->image->sharpen(15);
quality() Is used to adjust the image quality by a specified percentage. This method is chainable.
Note: The method is for reducing the quality of an image, in order to reduce the file size of the image, saving bandwidth and load time. It cannot be used to actually improve the quality of an input image.
Example:
// Reduce image quality to 75 percent of original $this->image->quality(75);
save($new_image = FALSE, $chmod = 0644, $keep_actions = FALSE) Is used to save the image to a file on disk. This method is NOT chainable. The default is to overwrite the input image file. Accepts a relative or absolute file path.
Example:
// Save image and overwrite the input image file $this->image->save(); // $this->image->save('./new-image.jpg'); // Save image to a new file.
render($keep_actions = FALSE) is used to output the image to the browser. This method is NOT chainable. It means that the headers corresponding to the image format are sent and the raw image stream with manipulation applied will be outputted directly to the browser. Returns TRUE on success or FALSE on failure.
Example:
$image = new Image($dir.'moo.jpg'); // Instantiate the library $image->resize(400, NULL)->crop(400, 350, 'top')->sharpen(20)->quality(75); // apply image manipulations // Output the image directly to the browser $this->image->render();
__get() is used to handle retrieval of pre-save image properties. Properties available are:
Place this code into a controller:
// The original image is located in folder /application/upload. $dir = str_replace('\\', '/', realpath(dirname(__FILE__).'/../upload')).'/'; $image = new Image($dir.'moo.jpg'); // Instantiate the library $image->resize(400, NULL)->crop(400, 350, 'top')->sharpen(20)->quality(75); // apply image manipulations $image->save($dir.'super-cow-crop.jpg'); // Write the changed image to a new file in the original input folder. Manipulations are discarded after the save call ($keep_action default TRUE). echo Kohana::debug($image); // Display some useful info about the operation **for debugging only**. $image->resize(300, NULL); // Resize the original image $image->save($dir.'super-cow-resize.jpg', TRUE); // Write the changed image to a new file in the original input folder $image->crop(300, 250, 'top'); // Resize and crop the original image ($keep_action set to TRUE means that resize manipulation has been kept after the save method call).
