Image - Classes - FuelPHP Documentation

Image クラス

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.

設定

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

パラメータ	型	規定値	説明
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

パラメータ

パラメータ	規定値	説明
`$config`	`array()`	An array of configuration options for the Image_Driver instance

返り値 Image_Driver

例

$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

パラメータ

パラメータ	規定値	説明
`$index`	必須	The index to be set, or an array of configuration options.
`$value`	`null`	The value to be set if $index is not an array.

返り値 Image_Driver

例

// 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

パラメータ

パラメータ	規定値	説明
`$filename`	必須	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.

返り値 Image_Driver

例

// 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

パラメータ

パラメータ	規定値	説明
`$x1`	必須	The position of the first coord on the x-axis.
`$y1`	必須	The position of the first coord on the y-axis.
`$x2`	必須	The position of the second coord on the x-axis.
`$y2`	必須	The position of the second coord on the y-axis.

返り値 Image_Driver

例

// 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

パラメータ

パラメータ	規定値	説明
`$width`	必須	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.

返り値 Image_Driver

例

// 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

パラメータ

パラメータ	規定値	説明
`$width`	必須	The new width of the image.
`$height`	`null`	The new height of the image

返り値 Image_Driver

例

// 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

パラメータ

パラメータ	規定値	説明
`$degrees`	必須	The degrees to rotate the image by. Accepts positive and negatives.

返り値 Image_Driver

例

// 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);

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

Adds a watermark to the image.

Static Yes

パラメータ

パラメータ	規定値	説明
`$filename`	必須	The location of the image file to use as a watermark.
`$position`	必須	The position of the watermark, accepts "(top\|center\|middle\|bottom) (left\|center\|middle\|bottom)".
`$padding`	`5`	The amount of padding from the edge, in pixels.

返り値 Image_Driver

例

// 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 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"

border($size, $color = null)

Adds a border to the image..

Static Yes

パラメータ

パラメータ	規定値	説明
`$size`	必須	The size of the border in pixels.
`$color`	`null`	The color of the border, defaults to the background color.

返り値 Image_Driver

例

// 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

パラメータ

パラメータ	規定値	説明
`$maskimage`	必須	The location of the image to mask with.

返り値 Image_Driver

例

// 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

パラメータ

パラメータ	規定値	説明
`$radius`	必須	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.

返り値 Image_Driver

例

// 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

パラメータ

パラメータ	規定値	説明
`$filename`	`null`	The location of the file to get sizes for..

返り値 stdClass

例

// Get sizes for a referenced image
$sizes = Image::sizes('filename.gif');

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

grayscale()

Turns the image into a grayscale version.

Static	Yes
パラメータ	N/A
返り値	Image_Driver
例	`// Grayscale image Image::load('filename.gif') ->grayscale();`

save($filename, $permissions = null)

Saves the image, and optionally attempts to set permissions.

Static Yes

パラメータ

パラメータ	規定値	説明
`$filename`	必須	The location where to save the image. 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

返り値 void

例

// 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

パラメータ

パラメータ	規定値	説明
`$append`	必須	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

返り値 void

例

// 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

パラメータ

パラメータ	規定値	説明
`$filetype`	`null`	The filetype to output the image as (Ex: png, gif, jpeg, ect). Defaults to the loaded file's extension.

返り値 void

例

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

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