Image

Aplus Framework Image Library.

Installation

The installation of this library can be done with Composer:

composer require aplus/image

Instantiating a new Image

<?php
require __DIR__ . '/vendor/autoload.php';

use Framework\Image\Image;

$filename = __DIR__ . '/tree.png';

$image = new Image($filename);

Detecting if a file is Acceptable

Indicates if a given file has an acceptable (PNG, JPEG or GIF) image type.

$isAcceptable = Image::isAcceptable($filename); // bool

Getting Image Information

Get Width

Gets the image width.

$width = $image->getWidth(); // int

Get Height

Gets the image height.

$height = $image->getHeight(); // int

Get Resolution

Gets the image resolution.

$resolution = $image->getResolution(); // array of integers

The $resolution value will be an array like the following:

[
    'horizontal' => 300,
    'vertical' => 300,
]

Get Quality

Gets the image quality/compression level.

$quality = $image->getQuality(); // int or null

Returns an integer for PNG and JPEG types or null for GIF.

Get MIME Type

Gets the image MIME type.

$mime = $image->getMime(); // string

Returns a string with the MIME type (e.g. image/png).

Get Extension

Gets a file extension based in the image type.

$extension = $image->getExtension(); // string or false

Returns a string with the extension (e.g. .png) or false on fail.

Get GdImage

Gets the image GD instance.

$gdImage = $image->getInstance(); // GdImage

Setting new Properties

Set Quality

Sets the image quality/compression level.

$image->setQuality(8); // static

The quality value must not be set on GIF images.
PNG images must have a value between 0 and 9.
JPEG images must have a value between 0 and 100.

Set Resolution

Sets the image resolution.

$horizontal = 96;
$vertical = 96;
$image->setResolution($horizontal, $vertical); // static

The resolution values are in DPI. Default is set 96 to both.

Set GdImage

Sets the image GD instance.

$gdImage = imagecreatefrompng($filename);
$image->setInstance($gdImage); // static

Image Manipulation

The Image class has methods to Crop, Filter, Flatten, Flip, Rotate, Scale and add Watermark.

The image below is the original used for our demonstration. It is a PNG file, with transparent background.

Crop

Crops the image.

$width = 200;
$height = 200;
$marginLeft = 100; 
$marginTop = 100;
$image->crop($width, $height, $marginLeft, $marginTop); // static

Argument value sizes are in pixels.
If a margin is negative or larger than the canvas, it will add extra space to the image size.

The cropped image will be like the following:

Filter

Applies a filter to the image.

$image->filter(IMG_FILTER_NEGATE); // static

The first param is an

image filter constant. - The second param is an spread of image filter arguments.

The filtered image will be like the following:

Flatten

Flattens the image.

Replaces transparency with an RGB color.

$red = 128; 
$green = 0;
$blue = 128;
$image->flatten($red, $green, $blue); // static

The flattened image will be like the following:

Flip

Flips the image.

$direction = 'horizontal';
$image->flip($direction); // static

The allowed $direction values are:

h or horizontal to horizontal flip.
v or vertical to vertical flip.
b or both to both, horizontal and vertical, flip.

The flipped image will be like the following:

Rotate

Rotates the image with a given angle.

$angle = 45;
$image->rotate($angle); // static

The rotation angle is in degrees. Clockwise direction.

The rotated image will be like the following:

Scale

Scales the image.

$width = 80;
$height = -1;
$image->scale($width, $height); // static

Width and height sizes are in pixels.
Height can be -1 to be automatically proportional to the width.

The scaled image will be like the following:

Watermark

Adds a watermark to the image.

$watermark = new Image($filename);
$watermark->scale(100);
$horizontalPosition = -10;
$verticalPosition = -10;
$image->watermark(
    $watermark,
    $horizontalPosition,
    $verticalPosition
); // static

Watermark must be an Image instance.
Horizontal position direction is left-to-right when the value is positive, otherwise is right-to-left.
Vertical position direction is top-to-bottom when the value is positive, otherwise is bottom-to-top.

The watermarked image will be like the following:

Rendering Methods

Send

When necessary, it is possible to send the Image contents directly to the PHP Output Buffer, to the User-Agent, to the browser...

$image->send(); // bool

Save

To save the Image contents in a file, use the save method:

$image->save($filename); // bool

The $filename argument is optional.

The default $filename value is null, which indicates to save the contents in the original file set in the constructor.

Render

When need to set the Image contents in a variable, use the render method:

$contents = $image->render(); // string

Get Data URL

It is possible embed the Image contents in a document with the Data URL format.

$dataUrl = $image->getDataUrl(); // string

The $dataUrl value will be like:

data:image/png;base64,...

Where ... is the base64 encoded binary image contents.

JSON Serialize

The Image class implements the JsonSerializable interface.

When an Image object is inside a value to be JSON encoded, it is transformed in a Data URL string:

$data = [
    'id' => 1,
    'src' => $image,
];
$json = json_encode($data);

The JSON pretty print string will be like this:

{
    "id": 1,
    "src": "data:image/png;base64,..."
}

To String

The Image class implements the Stringable interface.

When an Image object is converted to string, it is transformed to the Data URL format:

$dataUrl = (string) $image;