You are browsing the unmaintained documentation for old Nette 2.1. See documentation for current Nette.

Image Functions

The Nette\Image class simplifies image manipulation, such as resizing, cropping, sharpening, drawing, or merging multiple images.

PHP has an extensive set of functions for manipulating images. But the API is not very nice. It wouldn't be a Nette Framework to come up with a sexy API.

Installation:

composer require nette/utils

Following examples assume the following class alias is defined:

use Nette\Image;

Creating an Image

We'll create a new TRUE color image, for example with dimensions of 100×200:

$image = Image::fromBlank(100, 200);

Optionally, you can specify a background color (default is black):

$image = Image::fromBlank(100, 200, Image::rgb(125, 0, 0));

Or we load the image from a file:

$image = Image::fromFile('nette.jpg');

Need to detect the image format when loading? The method returns format in the second parameter:

$image = Image::fromFile('nette.jpg', $type);
// $type is Image::JPEG, Image::PNG, Image::GIF

Save the Image

The image can be saved to a file:

$image->save('resampled.jpg');

We can specify the compression quality in the range 0..100 for JPEG (default 85) and WEBP (default 80) and 0..9 for PNG (default 9):

$image->save('resampled.jpg', 80); // JPEG, quality 80%

If the format is not obvious from the file extension, you can specify it with one of the constants Image::JPEG, Image::PNG, Image::GIF:

$image->save('resampled.tmp', NULL, Image::JPEG);

The image can be written to a variable instead of to disk:

$data = $image->toString(Image::JPEG, 80); // JPEG, quality 80%

or send directly to the browser with the appropriate HTTP header Content-Type:

// sends header Content-Type: image/png
$image->send(Image::PNG);

Image Resize

A common operation is to resize an image. The current dimensions are returned by methods getWidth() and getHeight().

The method resize() is used for resizing. This is example of proportional size change so that it does not exceed 500×300 pixels (either the width will be exactly 500px or the height will be exactly 300px, one of dimensions is calculated to maintain the aspect ratio):

$image->resize(500, 300);

It's possible to set only one dimension and the second one will be calculated:

$image->resize(500, NULL); // width 500px, height auto

$image->resize(NULL, 300); // width auto, height 300px

Any dimension can be specified in percentages:

$image->resize('75%', 300); // 75 % × 300px

The behavior of the resize function could be affected with following flags:

Flag Description
Image::FIT (default) resulting dimensions will be less or equal as specified
Image::FILL fills the target area and possibly extends it in one direction
Image::EXACT fills the whole area and cuts what exceeds
Image::SHRINK_ONLY just scales down (does not extend a small image)
Image::STRETCH does not keep the aspect ratio

The flags are passed as the third argument of the function:

$image->resize(500, 300, Image::STRETCH);

Flags can be combined:

$image->resize(500, 300, Image::SHRINK_ONLY | Image::STRETCH);

Images can be flipped vertically or horizontally by specifying one of the dimensions (or both) as a negative number:

$flipped = $image->resize(NULL, '-100%'); // flip vertical

$flipped = $image->resize('-100%', '-100%'); // rotate by 180°

$flipped = $image->resize(-125, 500); // resize & flip horizontal

After reducing the image we can improve it by sharpening:

$image->sharpen();

Cropping

The method crop() is used for cropping:

$image->crop($left, $top, $width, $height);

As with resize(), all values can be specified in percentages. The percentages for $left and $top are calculated from the remaining space, similar to the CSS property background-position:

$image->crop('100%', '50%', '80%', '80%');

Drawing and Editing

You can draw, you can write, you can use all PHP functions for working with images, such as imagefilledellipse(), but using object style:

$image->filledEllipse($cx, $cy, $width, $height, Image::rgb(255, 0, 0, 63));

See Overview of Methods.

Merge Multiple Images

You can easily place another image into the image:

$logo = Image::fromFile('logo.png');
$blank = Image::fromBlank(320, 240, Image::rgb(52, 132, 210));

// coordinates can be set also in percentage
$blank->place($logo, '80%', '80%'); // near the right bottom corner

When pasting, the alpha channel is respected, in addition, we can influence the transparency of the inserted image (we will create a so-called watermark):

$blank->place($image, '80%', '80%', 25); // transparency is 25 %

Such API is really a pleasure to use, isn't it?