Package: Zebra_Image

Class: Zebra_Image

source file: /Zebra_Image.php

Class Overview


A compact (one-file only) and lightweight PHP library for image manipulation providing methods for performing several types of image manipulation operations and applying filters to images.

Read more here

Author(s):

Version:

  • 2.2.7 (last revision: August 21, 2017)

Copyright:

  • (c) 2006 - 2017 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 you set this 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. The php_mbstring.dll DLL must be loaded before the php_exif.dll DLL so adjust your php.ini accordingly. See the PHP manual

Default is FALSE

Tags:
since: 2.2.4
access: public
top

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

Tags:
access: public
top

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

Tags:
access: public
top

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 format
  • 5: unsupported target file format
  • 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).

Tags:
access: public
top

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.

Range is 0 - 100

Default is 85

Tags:
access: public
top

integer $png_compression

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

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

Range is 0 - 9

Default is 9

Tags:
since: 2.2
access: public
top

boolean $preserve_aspect_ratio

Specifies whether, upon resizing, images should preserve their aspect ratio.

Available only for the resize() method

Default is TRUE

Tags:
access: public
top

boolean $preserve_time

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

Default is TRUE

Tags:
since: 1.0.4
access: public
top

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" PHP function which is available only for PHP version 5.1.0+, and will leave the images unaltered for older versions!

Default is FALSE

Tags:
since: 2.2
access: public
top

string $source_path

Path to an image file to apply the transformations to.

Supported file types are GIF, PNG and JPEG.

Tags:
access: public
top

string $target_path

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

Can be a different than source_path - the type of the transformed image will be as indicated by the file's extension (supported file types are GIF, PNG and JPEG).

Tags:
access: public
top

Class methods

constructor __construct()

void __construct ( )

Constructor of the class.

Initializes the class and the default properties

Tags:
access: public
top

method apply_filter()

boolean apply_filter ( string $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.

  1. // include the Zebra_Image library
  2. require 'path/to/Zebra_Image.php';
  3.  
  4. // instantiate the class
  5. $img new Zebra_Image();
  6.  
  7. // a source image
  8. $img->source_path 'path/to/source.ext';
  9.  
  10. // path to where should the resulting image be saved
  11. // note that by simply setting a different extension to the file will
  12. // instruct the script to create an image of that particular type
  13. $img->target_path 'path/to/target.ext';
  14.  
  15. // apply the "grayscale" filter
  16. $img->apply_filter('grayscale');
  17.  
  18. // apply the "contrast" filter
  19. $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:

  1. // create a sepia effect
  2. // note how we're applying multiple filters at once
  3. // each filter is in its own array
  4. $img->apply_filter(array(
  5.  
  6.     // first we apply the "grayscale" filter
  7.     array('grayscale'),
  8.  
  9.     // then we apply the "colorize" filter with 90, 60, 40 as
  10.     // the values for red, green and blue
  11.     array('colorize'906040),
  12.  
  13. ));
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
access: public
Parameters:
string $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 to 255;
  • colorize - adds (subtracts) specified RGB values to each pixel; use arg1, arg2 and arg3 in the form of red, green, blue and arg4 for the alpha channel. the range for each color is -255 to 255 and 0 to 127 for alpha; alpha support is available only 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;
  • gausian_blur - blurs the image using the Gaussian method;
  • grayscale - converts the image into grayscale;
  • edgedetect - uses edge detection to highlight the edges in the image;
  • emboss - embosses the image;
  • 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;
  • 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;
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)
  • smooth - sets the smoothness level
  • pixelate - sets the block size, in pixels
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).
mixed $arg3 Used by the following filters:
  • colorize - sets the value of the blue component (-255 to 255)
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.
top

method crop()

boolean crop ( integer $start_x , integer $start_y , integer $end_x , integer $end_y )

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

  1. // include the Zebra_Image library
  2. require 'path/to/Zebra_Image.php';
  3.  
  4. // instantiate the class
  5. $img new Zebra_Image();
  6.  
  7. // a source image
  8. $img->source_path 'path/to/source.ext';
  9.  
  10. // path to where should the resulting image be saved
  11. // note that by simply setting a different extension to the file will
  12. // instruct the script to create an image of that particular type
  13. $img->target_path 'path/to/target.ext';
  14.  
  15. // crop a rectangle of 100x100 pixels, starting from the top-left corner
  16. $img->crop(00100100);
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
access: public
Parameters:
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
top

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

  1. // include the Zebra_Image library
  2. require 'path/to/Zebra_Image.php';
  3.  
  4. // instantiate the class
  5. $img new Zebra_Image();
  6.  
  7. // a source image
  8. $img->source_path 'path/to/source.ext';
  9.  
  10. // path to where should the resulting image be saved
  11. // note that by simply setting a different extension to the file will
  12. // instruct the script to create an image of that particular type
  13. $img->target_path 'path/to/target.ext';
  14.  
  15. // flip the image both horizontally and vertically
  16. $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
access: public
top

method flip_horizontal()

boolean flip_horizontal ( )

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

  1. // include the Zebra_Image library
  2. require 'path/to/Zebra_Image.php';
  3.  
  4. // instantiate the class
  5. $img new Zebra_Image();
  6.  
  7. // a source image
  8. $img->source_path 'path/to/source.ext';
  9.  
  10. // path to where should the resulting image be saved
  11. // note that by simply setting a different extension to the file will
  12. // instruct the script to create an image of that particular type
  13. $img->target_path 'path/to/target.ext';
  14.  
  15. // flip the image horizontally
Tags:
return:

Returns TRUE on success or FALSE on error.

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

access: public
top

method flip_vertical()

boolean flip_vertical ( )

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

  1. // include the Zebra_Image library
  2. require 'path/to/Zebra_Image.php';
  3.  
  4. // instantiate the class
  5. $img new Zebra_Image();
  6.  
  7. // a source image
  8. $img->source_path 'path/to/source.ext';
  9.  
  10. // path to where should the resulting image be saved
  11. // note that by simply setting a different extension to the file will
  12. // instruct the script to create an image of that particular type
  13. $img->target_path 'path/to/target.ext';
  14.  
  15. // flip the image vertically
  16. $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.

access: public
top

method resize()

boolean resize ( [ integer $width = 0] , [ integer $height = 0] , [ int $method = ZEBRA_IMAGE_CROP_CENTER] , [ hexadecimal $background_color = '#FFFFFF'] )

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

  1. // include the Zebra_Image library
  2. require 'path/to/Zebra_Image.php';
  3.  
  4. // instantiate the class
  5. $img new Zebra_Image();
  6.  
  7. // a source image
  8. $img->source_path 'path/to/source.ext';
  9.  
  10. // path to where should the resulting image be saved
  11. // note that by simply setting a different extension to the file will
  12. // instruct the script to create an image of that particular type
  13. $img->target_path 'path/to/target.ext';
  14.  
  15. // apply a "sharpen" filter to the resulting images
  16. $img->sharpen_images true;
  17.  
  18. // resize the image to exactly 150x150 pixels, without altering aspect ratio, by using the CROP_CENTER method
  19. $img->resize(150150ZEBRA_IMAGE_CROP_CENTER);
Tags:
return:

Returns TRUE on success or FALSE on error.

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

access: public
Parameters:
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 - (also see 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 the 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 - (also see 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 still apply).

If either height or width are set to 0, the script will consider the value of the 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

hexadecimal $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 in this case.

Default is #FFFFFF.

top

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.

  1. // include the Zebra_Image library
  2. require 'path/to/Zebra_Image.php';
  3.  
  4. // instantiate the class
  5. $img new Zebra_Image();
  6.  
  7. // a source image
  8. $img->source_path 'path/to/source.ext';
  9.  
  10. // path to where should the resulting image be saved
  11. // note that by simply setting a different extension to the file will
  12. // instruct the script to create an image of that particular type
  13. $img->target_path 'path/to/target.ext';
  14.  
  15. // rotate the image 45 degrees, clockwise
  16. $img->rotate(45);
Tags:
return:

Returns TRUE on success or FALSE on error.

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

access: public
Parameters:
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 in this case.

Default is -1.

top