Zebra_Image, a compact and lightweight image manipulation PHP library - Docs For Class Zebra_Image

Element index

Project's homepage

Zebra_Image

Classes:

Zebra_Image

Hi there!

That's me, Stefan Gabos, the author of this library.

If you like this project, please star it on GitHub — thank you!

I have a few other projects that you might be interested in — check them out if you have the time.

Class: Zebra_Image

source file: /Zebra_Image.php

A single-file, lightweight PHP library designed for efficient image manipulation featuring methods for modifying images and applying filters Supports WEBP format.

Read more here

Author(s):

Stefan Gabos
contact@stefangabos.ro

Version:

2.8.2 (last revision: January 25, 2023)
See CHANGELOG

License:

GNU LESSER GENERAL PUBLIC LICENSE

Copyright:

© 2006 - 2023 Stefan Gabos

Class properties

boolean $auto_handle_exif_orientation

If set to true, JPEG images will be auto-rotated according to the Exif Orientation Tag so that they are always shown correctly.

If set to true you must also enable exif-support with --enable-exif.
Windows users must enable both the php_mbstring.dll and php_exif.dll DLL's in php.ini.
php_mbstring.dll must be loaded before php_exif.dll, so adjust your php.ini accordingly. See the manual.

Default is false

Tags

since:

2.2.4

boolean $bmp_compressed

Indicates whether BMP images should be compressed with run-length encoding (RLE), or not.

Used only if PHP version is 7.2.0+ and the file at target_path is a BMP image, or it will be ignored otherwise.

Default is TRUE

Tags

since:

2.8.1

integer $chmod_value

Indicates the file system permissions to be set for newly created images.

Better is to leave this setting as it is.

If you know what you are doing, here is how you can calculate the permission levels:

400 Owner Read
200 Owner Write
100 Owner Execute
40 Group Read
20 Group Write
10 Group Execute
4 Global Read
2 Global Write
1 Global Execute

Default is 0755

boolean $enlarge_smaller_images

If set to false, images having both width and height smaller than the required width and height will be left untouched. jpeg_quality and png_compression will still apply!

Available only for the resize() method.

Default is true

integer $error

In case of an error read this property's value to see the error's code.

Possible error codes are:

1 - source file could not be found
2 - source file is not readable
3 - could not write target file
4 - unsupported source file type (note that you will also get this for animated WEBP images!)
5 - unsupported target file type
6 - GD library version does not support target file format
7 - GD library is not installed!
8 - "chmod" command is disabled via configuration
9 - "exif_read_data" function is not available

Default is 0 (no error)

boolean $jpeg_interlace

Indicates whether the created image should be saved as a progressive JPEG.

Used only if the file at target_path is a JPG/JPEG image, or will be ignored otherwise.

Default is false

Tags

since:

2.5.0

integer $jpeg_quality

Indicates the quality of the output image (better quality means bigger file size).

Used only if the file at target_path is a JPG/JPEG image, or it will be ignored otherwise.

Range is 0 - 100.

Default is 85

integer $png_compression

Indicates the compression level of the output image (lower compression means bigger file size).

Used only if PHP version is 5.1.2+ and the file at target_path is a PNG image, or it will be ignored otherwise.

Range is 0 - 9.

Default is 9

Tags

since:

2.2

boolean $preserve_aspect_ratio

Specifies whether upon resizing images should preserve their aspect ratio.

Available only for the resize() method.

Default is true

boolean $preserve_time

Indicates whether a target file should preserve the source file's date/time.

Default is true

Tags

since:

1.0.4

boolean $sharpen_images

Indicates whether the target image should have a sharpen filter applied to it.

Can be very useful when creating thumbnails and should be used only when creating thumbnails.

The sharpen filter relies on the imageconvolution function which is available for PHP version 5.1.0+, and will leave the images unaltered for older versions!

Default is false

Tags

since:

2.2

string $source_path

Path to an image file to apply the transformations to.

Supported file types are BMP, GIF, JPEG, PNG and WEBP.

WEBP support is available for PHP version 7.0.0+.

Note that even though WEBP support was added to PHP in version 5.5.0, it only started working with version 5.5.1, while support for transparency was added with version 7.0.0. As a result, I decided to make it available only if PHP version is at least 7.0.0

Animated WEBP images are not currently supported by GD. See here and here.

BMP support is available for PHP version 7.2.0+

string $target_path

Path (including file name) to where to save the transformed image.

Can be a different format than the file at source_path. The format of the transformed image will be determined by the file's extension. Supported file types are BMP, GIF, JPEG, PNG and WEBP.

WEBP support is available for PHP version 7.0.0+.

Note that even though WEBP support was added to PHP in version 5.5.0, it only started working with version 5.5.1, while support for transparency was added with version 7.0.0. As a result, I decided to make it available only if PHP version is at least 7.0.0

Animated WEBP images are not currently supported by GD. See here and here.

BMP support is available for PHP version 7.2.0+

integer $webp_quality

Indicates the quality level of the output image.

Used only if PHP version is 7.0.0+ and the file at target_path is a WEBP image, or it will be ignored otherwise.

Range is 0 - 100

Default is 80

Tags

since:

2.6.0

Class methods

constructor __construct()

void __construct ()

Constructor of the class.

Initializes the class and the default properties.

method apply_filter()

boolean apply_filter ( mixed $filter , [ mixed $arg1 = '' ] , [ mixed $arg2 = '' ] , [ mixed $arg3 = '' ] , [ mixed $arg4 = '' ] )

Applies one or more filters to the image given as source_path and outputs it as the file specified as target_path.

This method is available only if the imagefilter function is available (available from PHP 5+), and will leave images unaltered otherwise.

// include the Zebra_Image library
// (you don't need this if you installed using composer)
require 'path/to/Zebra_Image.php';
// instantiate the class
$img = new Zebra_Image();
// a source image
// (where "ext" is one of the supported file types extension)
$img->source_path = 'path/to/source.ext';
// path to where should the resulting image be saved
// note that by simply setting a different extension to the file will
// instruct the script to create an image of that particular type
$img->target_path = 'path/to/target.ext';
// apply the "grayscale" filter
$img->apply_filter('grayscale');
// apply the "contrast" filter
$img->apply_filter('contrast', -20);

You can also apply multiple filters at once. In this case, the method requires a single argument, an array of arrays, containing the filters and associated arguments, where applicable:

// create a sepia effect
// note how we're applying multiple filters at once
// each filter is in its own array
$img->apply_filter(array(
// first we apply the "grayscale" filter
array('grayscale'),
// then we apply the "colorize" filter with 90, 60, 40 as
// the values for red, green and blue
array('colorize', 90, 60, 40),
));

Arguments

mixed	$filter	The case-insensitive name of the filter to apply. Can be one of the following: brightness - changes the brightness of the image; use `arg1` to set the level of brightness; the range of brightness is `-255` - `255` colorize - adds specified RGB values to each pixel; use `arg1`, `arg2` and `arg3` in the form of `red`, `green` and `blue`, and `arg4` for the `alpha` channel; the range for each color is `-255` to `255` and `0` to `127` for the `alpha` where `0` indicates completely opaque while `127` indicates completely transparent; alpha support is available for PHP 5.2.5+ contrast - changes the contrast of the image; use `arg1` to set the level of contrast; the range of contrast is `-100` to `100` edgedetect - uses edge detection to highlight the edges in the image emboss - embosses the image gaussian_blur - blurs the image using the Gaussian method grayscale - converts the image into grayscale by changing the red, green and blue components to their weighted sum using the same coefficients as the REC.601 luma (Y') calculation; the alpha components are retained; for palette images the result may differ due to palette limitations mean_removal - uses mean removal to achieve a "sketchy" effect negate - reverses all the colors of the image pixelate - applies pixelation effect to the image; use `arg1` to set the block size and `arg2` to set the pixelation effect mode; this filter is available only for PHP 5.3.0+ selective_blur - blurs the image scatter - applies scatter effect to the image; use `arg1` and `arg2` to define the effect strength and additionally `arg3` to only apply the on select pixel colors smooth - makes the image smoother; use `arg1` to set the level of smoothness; applies a 9-cell convolution matrix where center pixel has the weight of `arg1` and others weight of 1.0; the result is normalized by dividing the sum with `arg1` + 8.0 (sum of the matrix); any float is accepted, large value (in practice: 2048 or) more) = no change
mixed	$arg1	Used by the following filters: brightness - sets the brightness level (`-255` to `255`) contrast - sets the contrast level (`-100` to `100`) colorize - sets the value of the red component (`-255` to `255`) pixelate - sets the block size, in pixels scatter - effect subtraction level; this must not be higher or equal to the addition level set with `arg3` smooth - sets the smoothness level
mixed	$arg2	Used by the following filters: colorize - sets the value of the green component (`-255` to `255`) pixelate - whether to use advanced pixelation effect or not (defaults to `false`) scatter - effect addition level
mixed	$arg3	Used by the following filters: colorize - sets the value of the blue component (`-255` to `255`) scatter - optional array indexed color values to apply effect at
mixed	$arg4	Used by the following filters: colorize - alpha channel; a value between `0` and `127`. `0` indicates completely opaque while `127` indicates completely transparent

Tags

return:

Returns true on success or false on error.

If imagefilter is not available, the method will return false without setting an error code.

If the requested filter doesn't exist, or invalid arguments are passed, the method will trigger a warning.

If false is returned and you are sure that imagefilter exists and that the requested filter is valid, check the error property to see the error code.

since: 2.2.2

method crop()

boolean crop ( integer $start_x , integer $start_y , integer $end_x , integer $end_y , [ mixed $background_color = -1 ] )

Crops a portion of the image given as source_path and outputs it as the file specified as target_path.

// include the Zebra_Image library
// (you don't need this if you installed using composer)
require 'path/to/Zebra_Image.php';
// instantiate the class
$img = new Zebra_Image();
// a source image
// (where "ext" is one of the supported file types extension)
$img->source_path = 'path/to/source.ext';
// path to where should the resulting image be saved
// note that by simply setting a different extension to the file will
// instruct the script to create an image of that particular type
$img->target_path = 'path/to/target.ext';
// crop a rectangle of 100x100 pixels, starting from the top-left corner
$img->crop(0, 0, 100, 100);

Arguments

integer	$start_x	x coordinate to start cropping from
integer	$start_y	y coordinate to start cropping from
integer	$end_x	x coordinate where to end the cropping
integer	$end_y	y coordinate where to end the cropping
mixed	$background_color	(Optional) A hexadecimal color value (like `#FFFFFF` or `#FFF`) used when the cropping coordinates are off-scale (negative values and/or values greater than the image's size) to fill the remaining space. When set to `-1` the script will preserve transparency for transparent `GIF` and `PNG` images. For non-transparent images the background will be black (`#000000`) in this case. Default is `-1`

Tags

return:

Returns true on success or false on error.

If false is returned, check the error property to see the error code.

since: 1.0.4

method flip_both()

boolean flip_both ()

Flips both horizontally and vertically the image given as source_path and outputs the resulted image as target_path.

// include the Zebra_Image library
// (you don't need this if you installed using composer)
require 'path/to/Zebra_Image.php';
// instantiate the class
$img = new Zebra_Image();
// a source image
// (where "ext" is one of the supported file types extension)
$img->source_path = 'path/to/source.ext';
// path to where should the resulting image be saved
// note that by simply setting a different extension to the file will
// instruct the script to create an image of that particular type
$img->target_path = 'path/to/target.ext';
// flip the image both horizontally and vertically
$img->flip_both();

Tags

return:

Returns true on success or false on error.

If false is returned, check the error property to see the error code.

since: 2.1

method flip_horizontal()

boolean flip_horizontal ()

Flips horizontally the image given as source_path and outputs the resulted image as target_path.

// include the Zebra_Image library
// (you don't need this if you installed using composer)
require 'path/to/Zebra_Image.php';
// instantiate the class
$img = new Zebra_Image();
// a source image
// (where "ext" is one of the supported file types extension)
$img->source_path = 'path/to/source.ext';
// path to where should the resulting image be saved
// note that by simply setting a different extension to the file will
// instruct the script to create an image of that particular type
$img->target_path = 'path/to/target.ext';
// flip the image horizontally
$img->flip_horizontal();

Tags

return:

Returns true on success or false on error.

If false is returned, check the error property to see the error code.

method flip_vertical()

boolean flip_vertical ()

Flips vertically the image given as source_path and outputs the resulted image as target_path.

// include the Zebra_Image library
// (you don't need this if you installed using composer)
require 'path/to/Zebra_Image.php';
// instantiate the class
$img = new Zebra_Image();
// a source image
// (where "ext" is one of the supported file types extension)
$img->source_path = 'path/to/source.ext';
// path to where should the resulting image be saved
// note that by simply setting a different extension to the file will
// instruct the script to create an image of that particular type
$img->target_path = 'path/to/target.ext';
// flip the image vertically
$img->flip_vertical();

Tags

return:

Returns true on success or false on error.

If false is returned, check the error property to see the error code.

method resize()

boolean resize ( [ integer $width = 0 ] , [ integer $height = 0 ] , [ int $method = ZEBRA_IMAGE_CROP_CENTER ] , [ mixed $background_color = -1 ] )

Resizes the image given as source_path and outputs the resulted image as target_path.

// include the Zebra_Image library
// (you don't need this if you installed using composer)
require 'path/to/Zebra_Image.php';
// instantiate the class
$img = new Zebra_Image();
// a source image
// (where "ext" is one of the supported file types extension)
$img->source_path = 'path/to/source.ext';
// path to where should the resulting image be saved
// note that by simply setting a different extension to the file will
// instruct the script to create an image of that particular type
$img->target_path = 'path/to/target.ext';
// apply a "sharpen" filter to the resulting images
$img->sharpen_images = true;
// resize the image to exactly 150x150 pixels, without altering
// aspect ratio, by using the CROP_CENTER method
$img->resize(150, 150, ZEBRA_IMAGE_CROP_CENTER);

Arguments

integer	$width	The width to resize the image to. If set to `0`, the width will be automatically adjusted, depending on the value of the `height` argument so that the image preserves its aspect ratio. If preserve_aspect_ratio is set to `true` and both this and the `height` arguments are values greater than `0`, the image will be resized to the exact required width and height and the aspect ratio will be preserved (see also the description for the `method` argument below on how can this be done). If preserve_aspect_ratio is set to `false`, the image will be resized to the required width and the aspect ratio will be ignored. If both `width` and `height` are set to `0`, a copy of the source image will be created. jpeg_quality and png_compression will still apply! If either `width` or `height` are set to `0`, the script will consider the value of preserve_aspect_ratio to bet set to `true` regardless of its actual value!
integer	$height	The height to resize the image to. If set to `0`, the height will be automatically adjusted, depending on the value of the `width` argument so that the image preserves its aspect ratio. If preserve_aspect_ratio is set to `true` and both this and the `width` arguments are values greater than `0`, the image will be resized to the exact required width and height and the aspect ratio will be preserved (see also the description for the `method` argument below on how can this be done). If preserve_aspect_ratio is set to `false`, the image will be resized to the required height and the aspect ratio will be ignored. If both `width` and `height` are set to `0`, a copy of the source image will be created. jpeg_quality and png_compression will If either `width` or `height` are set to `0`, the script will consider the value of preserve_aspect_ratio to bet set to `true` regardless of its actual value!
int	$method	(Optional) Method to use when resizing images to exact width and height while preserving aspect ratio. If the preserve_aspect_ratio property is set to `true` and both the `width` and `height` arguments are values greater than `0`, the image will be resized to the exact given width and height and the aspect ratio will be preserved by using on of the following methods: ZEBRA_IMAGE_BOXED - the image will be scaled so that it will fit in a box with the given width and height (both width/height will be smaller or equal to the required width/height) and then it will be centered both horizontally and vertically; the blank area will be filled with the color specified by the `bgcolor` argument. (the blank area will be filled only if the image is not transparent!) ZEBRA_IMAGE_NOT_BOXED - the image will be scaled so that it could fit in a box with the given width and height but will not be enclosed in a box with given width and height. The new width/height will be both smaller or equal to the required width/height. ZEBRA_IMAGE_CROP_TOPLEFT ZEBRA_IMAGE_CROP_TOPCENTER ZEBRA_IMAGE_CROP_TOPRIGHT ZEBRA_IMAGE_CROP_MIDDLELEFT ZEBRA_IMAGE_CROP_CENTER ZEBRA_IMAGE_CROP_MIDDLERIGHT ZEBRA_IMAGE_CROP_BOTTOMLEFT ZEBRA_IMAGE_CROP_BOTTOMCENTER ZEBRA_IMAGE_CROP_BOTTOMRIGHT For the methods involving crop, first the image is scaled so that both its sides are equal or greater than the respective sizes of the bounding box; next, a region of required width and height will be cropped from indicated region of the resulted image. Default is `ZEBRA_IMAGE_CROP_CENTER`
mixed	$background_color	(Optional) The hexadecimal color (like `#FFFFFF` or `#FFF`) of the blank area. See the `method` argument. When set to `-1` the script will preserve transparency for transparent `GIF` and `PNG` images. For non-transparent images the background will be white (`#FFFFFF`) in this case. Default is `-1`

Tags

return:

Returns true on success or false on error.

If false is returned, check the error property to see what went wrong.

method rotate()

boolean rotate ( double $angle , [ mixed $background_color = -1 ] )

Rotates the image given as source_path and outputs the resulted image as target_path.

// include the Zebra_Image library
// (you don't need this if you installed using composer)
require 'path/to/Zebra_Image.php';
// instantiate the class
$img = new Zebra_Image();
// a source image
// (where "ext" is one of the supported file types extension)
$img->source_path = 'path/to/source.ext';
// path to where should the resulting image be saved
// note that by simply setting a different extension to the file will
// instruct the script to create an image of that particular type
$img->target_path = 'path/to/target.ext';
// rotate the image 45 degrees, clockwise
$img->rotate(45);

Arguments

double

$angle

Angle by which to rotate the image clockwise.

Between 0 and 360.

mixed

$background_color

(Optional) The hexadecimal color (like #FFFFFF or #FFF) of the uncovered zone after the rotation.

When set to -1 the script will preserve transparency for transparent GIF and PNG images. For non-transparent images the background will be white (#FFFFFF) in this case.

Default is -1.

Tags

return:

Returns true on success or false on error.

If false is returned, check the error property to see the error code.

Documentation generated on Wed, 25 Jan 23