Stefan Gabos web developer extraordinaire

Tweet

Zebra_Image, a lightweight image manipulation library written in PHP

Get the latest updates on this PHP library via RSS

• 1. Overview
• 2. Features
• 3. Requirements
• 4. Installation
• 5. How to use
• 6. Download
• 7. Documentation
• 8. Changelog
• 9. Comments

This is a compact (one-file only), lightweight, object-oriented image manipulation library written in and for PHP, that provides methods for performing several types of image manipulation operations. It doesn’t require any external libraries other than the GD2 extension (with which PHP usually comes pre-compiled with).

With this library you can rescale, flip, rotate , crop and sharpen images. It supports loading and saving images in the GIF, JPEG and PNG formats and preserves transparency of GIF, PNG8 and PNG24 images.

Zebra_Image‘s code is heavily commented and generates no warnings/errors/notices when PHP’s error reporting level is set to E_ALL.

The cool thing about it is that it can re-size images to exact given width and height and still maintain aspect ratio by using one of the following methods:

1. the image will be scaled so that it will fit in a box with the given width and height and then it will be centered both horizontally and vertically in the box. The blank area will be filled with a specified color.
2. 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
3. after the image has been scaled so that its width and height are equal or greater than the required width and height respectively, a region of required width and height will be cropped from the top left corner of the resulted image.
4. after the image has been scaled so that its width and height are equal or greater than the required width and height respectively, a region of required width and height will be cropped from the center of the resulted image.

Here are the results of resizing a 800×573 pixels image to a 200×200 pixels image and preserving the aspect ratio by using each of the aforementioned methods:

Features review

• can be used to resize, flip, rotate, crop and sharpen images
• can resize images to *exact* size by automatically cropping them
• preserves transparency of GIF, PNG8 and PNG24 images
• code is heavily commented and generates no warnings/errors/notices when PHP’s error reporting level is set to E_ALL
• has comprehensive documentation

Requirements

PHP 4.4.9+, bundled GD 2.0.28+

Installation

Download the latest version, unpack it, and put it in a place accessible to your scripts.

How to use

<?php

    // load the image manipulation class
    require 'path/to/Zebra_Image.php';

    // create a new instance of the class
    $image = new Zebra_Image();

    // indicate a source image (a GIF, PNG or JPEG file)
    $image->source_path = 'path/to/image.png';

    // indicate a target image
    // note that there's no extra property to set in order to specify the target
    // image's type -simply by writing '.jpg' as extension will instruct the script
    // to create a 'jpg' file
    $image->target_path = 'path/to/image.jpg';

    // since in this example we're going to have a jpeg file, let's set the output
    // image's quality
    $image->jpeg_quality = 100;

    // some additional properties that can be set
    // read about them in the documentation
    $image->preserve_aspect_ratio = true;
    $image->enlarge_smaller_images = true;
    $image->preserve_time = true;

    // resize the image to exactly 100x100 pixels by using the "crop from center" method
    // (read more in the overview section or in the documentation)
    //  and if there is an error, check what the error is about
    if (!$image->resize(100, 100, ZEBRA_IMAGE_CROP_CENTER)) {

        // if there was an error, let's see what the error is about
        switch ($image->error) {

            case 1:
                echo 'Source file could not be found!';
                break;
            case 2:
                echo 'Source file is not readable!';
                break;
            case 3:
                echo 'Could not write target file!';
                break;
            case 4:
                echo 'Unsupported source file format!';
                break;
            case 5:
                echo 'Unsupported target file format!';
                break;
            case 6:
                echo 'GD library version does not support target file format!';
                break;
            case 7:
                echo 'GD library is not installed!';
                break;

        }

    // if no errors
    } else {

        echo 'Success!';

    }

?>

Download

version 2.2.1 (zip, 176.7Kb)

If you find this library to be useful to you, you can support the author by donating a small amount via PayPal:

You may also like:

• Zebra_Database, a MySQL database wrapper written in PHP
• Zebra_Form, a jQuery augmented PHP library for creating and validating forms
• Zebra_Mptt, a PHP implementation of the modified preorder tree traversal algorithm
• Zebra_Pagination, a generic pagination class written in PHP
• Zebra_Session, a wrapper for PHP's default session handling functions, using MySQL for storage

Documentation

Become a ninja. Read the comprehensive documentation.

Changelog

Click on a version to expand/collapse information.

version 2.2.1 (September 09, 2011)

• fixed two bugs that appeared since the last version that would cause the script to throw warnings; thanks to NIXin for reporting;

version 2.2 (September 06, 2011)

• a new property is now available: png_compression, which determines the compression level of PNG files; this value of this property is ignored for PHP versions older than 5.1.2; thanks to Julien for suggesting;
• a new property is now available: sharpen_images which, when enabled, will instruct the script to apply a “sharpen” filter to the resulting images; can be very useful when creating thumbnails but should be used only when creating thumbnails; the sharpen filter relies on PHP’s imageconvolution function which is available only for PHP version 5.1.0+, and will leave the images unaltered for older versions;
• added new cropping options: TOPCENTER, TOPRIGHT, MIDDLELEFT, MIDDLERIGHT, BOTTOMLEFT, BOTTOMCENTER, BOTTOMRIGHT; thanks to flam for suggesting;
• entire logic behind the resize method was rewritten;
• fixed a bug where the script would generate warnings if the chmod function was disabled via PHP configuration options; now it will not generate the warning but instead will set a value for the script’s error property;
• fixed a bug where if one would resize a transparent image and in the process would convert it to a JPEG (no transparency) and the resize method’s background_color argument was set to -1, the resulted image’s background color would be black; now it is white, as described in the documentation; thanks to Julien for reporting;

version 2.1.2 (May 09, 2011)

• fixed a bug when resizing images having height greater than width, and using the resize() method with only the height argument; thanks to Manuweb2 for reporting.

version 2.1.1 (March 24, 2011)

• fixed a bug where the script would produce warnings on some particular transparent GIF images; thanks to Olof Fredriksson for reporting.

version 2.1 (February 05, 2011)

• fixed a bug where the script would produce warnings on partially broken JPEG files and would not process the image; now the script will successfully handle such images;
• fixed a bug where the rotate method was not working correctly on transparent PNG/GIF images;
• improved overall handling of transparent images;
• a new method was added: “flip_both” which flips an image both vertically and horizontally;
• the code for flip_horizontal and flip_vertical methods was rewritten;
• a more explicit example was added;

version 2.0 (September 27, 2010)

• entire code was audited and improved;
• method names, method arguments and global properties were changed and therefore this version breaks compatibility with previous ones;
• resize() method was improved and now can resize an image to exact width and height and still maintain the aspect ratio by involving the crop() method;
• fixed a bug where the crop(), flip_horizontal() and flip_vertical() were not working correctly for transparent PNG files;
• some documentation refinements;

version 1.0.5 (August 23, 2007)

• fixed a bug where the resize() method would produce unexpected results when the actual width of the image was smaller than the value of the resizeToWidth property and resizeIfSmaller property was set to FALSE. in this case, if the height of the image was to be adjusted upwards, the width of the image was increased indefinitely not taking in account the value of resizeToWidth property;

version 1.0.4 (October 13, 2006)

• a new method was added – crop();
• a new property was added – preserveSourceFileTime which is by default set to TRUE and which instructs the scripts to preserve the date/time of the source files and pass it on to the target files; thanks to patrick from swederland;
• the flip_horizontal and flip_vertical methods were stil using the imagecopy function instead of using the imagecopyresampled function;
• the create_image_from_source_file() function was incorrectly checking for the existence of the source file: you could specify a valid path (but not a file) and the script would crash error because the path indeed existed even though it was not a file;
• the result of the create_image_from_source_file() private method was poorly implemented and the script could be easily crashed by specifying bogus source files;

version 1.0.3 (September 13, 2006)

• if invalid sizes were specified for resizing (i.e. string or negative numbers) the script would crash;
• resizing of transparent png24 files was not working; thanks mar251;
• working with png files would always make the value of the “error” property equal to 5 even if everything went well;
• when resizing, interpolation was not used and the resulting images were rough. now imagecopyresampled function is used instead of imagecopyresized; thanks Sabri;
• resizing was not working correctly in some cases;

version 1.0.2 (August 12, 2006)

• error checking for the source file was incorrectly implemented and the script would produce warnings and fatal errors if there were problems with the source file;
• properties will now have default values in PHP 4;

version 1.0.1 (August 11, 2006)

• after output, the file was chmod-ed incorrectly;
• the documentation now tells you about how to calculate the permission levels;

version 1.0 (August 04, 2006)

• initial release;

39 responses to “Zebra_Image, a lightweight image manipulation library written in PHP”

Follow the comments via RSS

• Relink, 2011-10-05, 07:06

  Hi. i really liked the script.
  but the most important feature is missing.
  Caching!

  Thanks.

  Reply
  
  • Stefan Gabos, 2011-10-05, 07:11

    i know what you refer to, but this library was not intended to resize image “on the fly”
    
• Enrique, 2011-10-05, 12:50

  The library looks amazing, but I’d like to know where did you get the elephant php plush?

  Reply
  
  • Stefan Gabos, 2011-10-05, 12:53

    as the note below the image says, the image is from a guy nicknamed “Laughing Squid” and is taken from Flickr
    
• Florin, 2011-11-30, 09:28

  Hi,

  How can i make this class resize an image in 3 different resolutions at the same time.

  Thanks
  Florin

  Reply
  
  • Stefan Gabos, 2011-11-30, 09:38

    // include the class
    require 'path/to/Zebra_Image.php';
    
    // create a new instance of the class
    $image = new Zebra_Image();
    
    // indicate a source image
    $image->source_path = 'path/to/source_image';
    
    // indicate first target image
    $image->target_path = 'path/to/target_image_1';
    $image->resize(100, 100);
    
    // indicate second target image
    $image->target_path = 'path/to/target_image_2';
    $image->resize(150, 150);
    
    // indicate a third target image
    $image->target_path = 'path/to/target_image_3';
    $image->resize(200, 200);
    
  • Florin, 2011-11-30, 10:09

    so simple thanks. Never thought at that!

    Thanks allot for your help and for your class
    
• Florin, 2011-11-30, 10:08

  i made it by jumping from page to page with the required variables in the url. But i’m sure there is an easy way.

  Waiting for your replay

  Reply
  
• Tomm Huth, 2012-01-12, 14:55

  Hi,

  This looks like great stuff, but i can’t get it to preserve the aspect ratio when resizing. I’ve tried the example given above the resize function, but it streches the image to fit the given dimensions. Any idea?

  Reply
  
  • Stefan Gabos, 2012-01-12, 15:01

    show me the code you’re using
    
• Tomm Huth, 2012-01-12, 15:13

  never mind me, figured it out. Love this class already!

  Reply
  
• perrie, 2012-02-04, 02:46

  Nice script i think its lacking a feature ex. if image has a longer width reduce the width to a given value while maintaining aspect ratio for the height and vice versa for an image with a longer height.. That way an image can stay within a bound and not be cropped..

  Reply
  
  • Stefan Gabos, 2012-02-04, 09:58

    this can already be done; read into the documentation about images resizing methods.

    in particular, for your case, you should be using something like

    require 'path/to/Zebra_Image.php';
    $img = new Zebra_Image();
    $img->source_path = 'path/to/source_image';
    $img->target_path = 'path/to/target_image';
    
    // resize the image to 150px width, and adjust the height
    // accordingly while keeping the aspect ratio
    $img->resize(150, 0, ZEBRA_IMAGE_NOT_BOXED);
    
    // resize the image to 150px height, and adjust the width
    // accordingly while keeping the aspect ratio
    $img->resize(0, 150, ZEBRA_IMAGE_NOT_BOXED);
    
• Nat, 2012-03-19, 22:25

  Amazing, I just added this to my Zend Framework Application Project. You saved me lots of coding time.
  Thanks Mate
  You are awesome

  Reply
  
• Shaik Amjad, 2012-04-17, 08:10

  It’s superb…

  Reply
  

Leave a Reply

Leave this field blank

Name*

Email*

Your email address will not be published

Website

Message*

You can use <strong>, <em>, <a>, <img>, <code>

Enter the characters that stand out in the image above

Characters are not case-sensitive