Image Class

The Image class is used to easily add common manipulations to an image such as resizing, cropping, and so on.

Limitations

The Image class has a few limitations that should be made aware of. First off, the GD library handles transparency quite badly. Due to this, Image::rotate() can not use transparent background. The rounding image in imagemagick is also flawed as images with transparent corners will get opaque circles in the corners.

Using multiple transformations in GD can result in abnormal results.

Configuration

The Image class accepts the following configuration options. Copy the file from fuel/core/config/image.php to fuel/app/config/image.php

Param Type Default Description
driver string
'gd'
Can be any name of a valid library, currently only 'gd', 'imagemagick' and 'imagick'
bgcolor string
null
Background in hex for (Ex: #ff0, #4f32de). Set to null for a transparent background.
watermark_alpha integer
75
The transparency of any watermarks applied to the image. Ranges from 0-100.
quality integer
100
Used for the quality in jpeg images and pngs.
filetype string
null
Defines an override default image type if no extension is given. If set to null, it inherits the original extension instead.
imagemagick_dir string
'/usr/bin/'
Where the imagemagick executables are stored. Must add leading slash.
temp_dir string
'/tmp/'
Temporary directory to store image files that are being edited.
temp_append string
'fuel_image'
The string to append to the temp images, as to avoid conflicts.
debug boolean
false
Turns on debug mode, which skips setting header and outputs debug information on an image.

Presets

Presets are a feature in the Image class that allow defining of a set of tasks in the config, and call that preset. An example is:

In app/config/image.php

/**
 * These presets allow you to call controlled manipulations.
 */
'presets' => array(
	'mypreset' => array(
		'bgcolor' => '#f00', // Set the background color red
		'filetype' => 'jpg', // Output as jpeg.
		'quality' => 75,
		'actions' => array(
			array('crop_resize', 200, 200),
			array('watermark', '$1'), // Note the $1 is a variable.
			array('output', 'png')
		)
	)
)

In your controller:

// 'watermark.gif' here replaces the $1 in array('watermark', '$1')
Image::load('filename.gif')->preset('mypreset', 'watermark.gif');

forge($config = array())

The forge method creates a new Image_Driver instance.

Static Yes
Parameters
Param Default Description
$config
array()
An array of configuration options for the Image_Driver instance
Returns Image_Driver
Example
$image = Image::forge();

// Or with optional config
$image = Image::forge(array(
	'quality' => 80
));
$image
	->load('image.png')
	->output('image.jpeg');

config($index, $value = null)

Changes the value of a configuration option.

Static Yes
Parameters
Param Default Description
$index Required The index to be set, or an array of configuration options.
$value
null
The value to be set if $index is not an array.
Returns Image_Driver
Example
// Resize an image, and change the background.
Image::load('filename.gif')
	->config('bgcolor', '#f00')
	->resize(100, 100, true, true);

load($filename, $return_data = false, $force_extension = false)

The load method attempts to load an image for editing.

Static Yes
Parameters
Param Default Description
$filename Required The path to the image file to be loaded.
$return_data
false
Determines whether to return image data, and only works with GD.
$force_extension
false
Whether or not to force the image extension (to $force_extension), and only works with GD.
Returns Image_Driver
Example
// Load image
Image::load('filename.gif');

// Upload an image and pass it directly into the Image::load method.
Upload::process(array(
	'path' => DOCROOT.DS.'files'
));

if (Upload::is_valid())
{
	$data = Upload::get_files(0);

	// Using the file upload data, we can force the image's extension
	// via $force_extension
	Image::load($data['file'], false, $data['extension'])
		->crop_resize(200, 200)
		->save('image');
} 

crop($x1, $y1, $x2, $y2)

Crops the image using coordinates or percentages.

Static Yes
Parameters
Param Default Description
$x1 Required The position of the first coord on the x-axis.
$y1 Required The position of the first coord on the y-axis.
$x2 Required The position of the second coord on the x-axis.
$y2 Required The position of the second coord on the y-axis.
Returns Image_Driver
Example
// For the purpose of this example, the image width and height are 200x200

// Crops the image from (20, 20) to (180, 180)
Image::load('filename.gif')
	->crop(20, 20, 180, 180);

// Crops the image from (40, 40) to (160, 160) using negatives.
Image::load('filename.gif')
	->crop(40, 40, -40, -40);

// Crops the image from (30, 30) to (170, 170) using a mix of percentages and negatives.
Image::load('filename.gif')
	->crop('15%', '15%', '-15%', '-15%');

resize($width, $height = null, $keepar = true, $pad = false)

Resizes the image. If the width or height is null, it will resize retaining the original aspect ratio.

Static Yes
Parameters
Param Default Description
$width Required The new width of the image.
$height
null
The new height of the image
$keepar
true
If set to true, will keep the Aspect Ratio of the image identical to the original.
$pad
false
If set to true and $keepar is true, it will pad the image with the configured bgcolor.
Returns Image_Driver
Example
// Resize using absolutes
Image::load('filename.gif')
	->resize(100, 100);

// Resize using percentages
Image::load('filename.gif')
	->resize('50%', '50%');

// Stretch the image to fit
Image::load('filename.gif')
	->resize(100, 100, false);

// Pad image as to keep input size and AR.
Image::load('filename.gif')
	->resize(100, 200, true, true);

crop_resize($width, $height = null)

Resizes the image and crops it to fit the given width and height.

Static Yes
Parameters
Param Default Description
$width Required The new width of the image.
$height
null
The new height of the image
Returns Image_Driver
Example
// Example usage, crop a 300x200 image to 200x200 would remove 50px on the top and bottom
Image::load('filename.gif')
	->crop_resize(200, 200);

rotate($degrees)

Rotates the image clockwise.

Static Yes
Parameters
Param Default Description
$degrees Required The degrees to rotate the image by. Accepts positive and negatives.
Returns Image_Driver
Example
// Rotates by 90 degrees clockwise
Image::load('filename.gif')
	->rotate(90);

// Rotates by 90 degrees counter clockwise
Image::load('filename.gif')
	->rotate(-90);

// Accepts numbers outside of the (-359, 359) range.
Image::load('filename')
	->rotate(450);

flip($direction)

Flip the image vertically and / or horizontally.

Static Yes
Parameters
Param Default Description
$direction Required the flip direction. Accepts "horizontal", "vertical" or "both"
Returns Image_Driver
Example
//Flip vertical
Image::load('filename.gif')
	->flip('vertical');

// Flip horizontal
Image::load('filename.gif')
	->flip('horizontal');

// Flip horizontal and vertical.
Image::load('filename')
	->flip('both');

watermark($filename, $position, $padding = array(5,5))

Adds a watermark to the image.

Static Yes
Parameters
Param Default Description
$filename Required The location of the image file to use as a watermark.
$position Required The position of the watermark, accepts "(top|center|middle|bottom|<int>) (left|center|middle|bottom|<int>)".
$padding
array(5,5)
The amount of padding from the edges, in pixels. The first value defines the vertical padding, the second value the horizontal padding. You can also pass an integer if both have the same value.
Returns Image_Driver
Example
// Watermarks the image in the top left corner with padding of 15 pixels
Image::load('filename.gif')
	->watermark('watermark.ext', "top left", 15);

// Watermarks the image in the top left corner with top-padding of 5px and a left-padding of 10px
Image::load('filename.gif')
	->watermark('watermark.ext', "top left", array(5, 10));

// Watermarks the image in the bottom right corner
Image::load('filename.gif')
	->watermark('watermark.ext', "bottom right");

// Watermarks the image in the center
Image::load('filename.gif')
	->watermark('watermark.ext', "center middle");
// "center middle" is identical to "center center", "middle middle", or "middle center"

// Watermarks the image in a fixed location, upper left at [10,40], with the default 5px padding
Image::load('filename.gif')
	->watermark('watermark.ext', "10 40");

border($size, $color = null)

Adds a border to the image..

Static Yes
Parameters
Param Default Description
$size Required The size of the border in pixels.
$color
null
The color of the border, defaults to the background color.
Returns Image_Driver
Example
// Make a 10px black border
Image::load('filename.gif')
	->border(10, '#000000');

// Make a 15px red, green, and blue border.
Image::load('filename.gif')
	->border(5, '#FF0000')
	->border(5, '#00FF00')
	->border(5, '#0000FF');

mask($maskimage)

Applies a mask to the image by blending the alpha channel of the mask with those of the loaded image.

Static Yes
Parameters
Param Default Description
$maskimage Required The location of the image to mask with.
Returns Image_Driver
Example
// Masks the image with mask.ext
Image::load('filename.gif')
	->mask('mask.ext');

rounded($radius, $sides = null, $antialias = null)

Applies rounded corners to the image.

Static Yes
Parameters
Param Default Description
$radius Required The location of the image to mask with.
$sides
null
Accepts any combination of "tl tr bl br" seperated by spaces, or null for all sides
$antialias
1
The distance away from the actual circle to anti-alias. 0 disables anti-aliasing.
Returns Image_Driver
Example
// Rounds the image 10px on all sides
Image::load('filename.gif')
	->rounded(10);

// Rounds the image 10px on the top
Image::load('filename.gif')
	->rounded(10, "tl tr");

// Rounds the image 10px on all sides with no antialiasing
Image::load('filename.gif')
	->rounded(10, null, 0);

sizes($filename = null)

Returns sizes for the currently loaded image, or the image given in the $filename.

Static Yes
Parameters
Param Default Description
$filename
null
The location of the file to get sizes for..
Returns stdClass
Example
// Get sizes for a referenced image
$sizes = Image::sizes('filename.gif');

// Returns
Object
(
    [width] => 500
    [height] => 400
)

extension()

Returns the extension of the file, which represents the type and is discovered at construction.

Static Yes
Parameters N/A
Returns string
Example
// Returns 'jpg'
$ext = Image::load('uploaded_file.jpg')
	->extension();

// Returns 'jpg', using the static instance
Image::forge($config, 'uploaded_file.jpg');
$ext = Image::extension();

// Save a PNG as a JPG
Image::load('placeholder.png')
	->output($ext);
							

grayscale()

Turns the image into a grayscale version.

Static Yes
Parameters N/A
Returns Image_Driver
Example
// Grayscale image
Image::load('filename.gif')
	->grayscale();

save($filename = null, $permissions = null)

Saves the image, and optionally attempts to set permissions.

Static Yes
Parameters
Param Default Description
$filename
null
The location where to save the image. If filename is null, loaded image filename will be used. If no extension is added, one will be appended based on the loaded file's extension.
$permissions
null
Accepts a unix-style permissions (Ex: 755), or null to not set permissions
Returns void
Example
// Saves to filename2.ext
Image::load('filename.gif')
	->save('filename2');

// Saves to filename2.png
Image::load('filename.gif')
	->save('filename2.png');

// Saves to filename2.ext while attempting to apply permissions
Image::load('filename.gif')
	->save('filename2', 755);

save_pa($prepend, $append = null, $extension = null, $permissions = null)

Saves the image to the same location with a prepended and/or appended filename, and optionally attempts to set permissions.

Static Yes
Parameters
Param Default Description
$append Required The string to add to the beginning of the filename.
$prepend
null
The string to add to the end of the filename, and before the extension.
$extension
null
Can set the new images extension, defaults to the loaded images extension if null.
$permissions
null
Accepts a unix-style permissions (Ex: 755), or null to not set permissions
Returns void
Example
// Saves to prepend_filename_append.gif
Image::load('filename.gif')
	->save_pa('prepend_', '_append');
							

output($filetype)

Outputs the image directly and sets headers.

Static Yes
Parameters
Param Default Description
$filetype
null
The filetype to output the image as (Ex: png, gif, jpeg, ect). Defaults to the loaded file's extension.
Returns void
Example
// Output as gif
Image::load('filename.gif')
	->output();

// Output as jpeg
Image::load('filename.gif')
	->output('jpeg');