View on GitHub


Encapsulates common GD library operations in PHP classes.

Download this project as a .zip file Download this project as a tar.gz file

Build Status


This package encapsulates some common GD library operations in PHP classes. It was created as part of the randomhost/webcamoverlay package but is released as a separate component so it can be used in other packages.

Because it was created as a dependency of the randomhost/webcamoverlay package, it does only support a small subset of the available image handling functions.


A basic approach at using this package could look like this:

namespace randomhost\Image;

require_once '/path/to/vendor/autoload.php';

// load base image
$image = Image::getInstanceByPath('image.png');

// load overlay image
$overlay = Image::getInstanceByPath('overlay.png');

// insert overlay image on top of base image at x 15, y 20
$image->merge($overlay, 15, 20);

// setup a red text overlay
$text = new Text\Generic($image);
        new Color(

// setup a white border for the previously defined text overlay
$text = new Text\Decorator\Border($text);
    new Color(

// render text overlay onto the image at x 20, y 10
    'Example text'

// render the image

This will instantiate two image objects using image files from the file system, merge the images and render an overlay text on top.

Assuming that you named this file image.php, you should now be able to access the image at

The Image object

The Image object represents an image in a (remote) filesystem or created in memory. It provides methods for retrieving information about the image and for merging other Image instances.


There are two methods for creating an Image object instance:

  1. Image::getInstanceByPath($path, $cacheDir = '')
    Creates an instance from an existing local or remote image file.
    • $path
      Path or URL to the image file.
    • $cacheDir
      Optional: Directory path for caching image files. This comes in handy when retrieving images from remote locations as caching them locally reduces the amount of HTTP requests which have to be made.
  2. Image::getInstanceByCreate($width, $height)
    Creates an empty instance with the given image dimensions which can be used to merge (multiple) other Image instances into it.
    • $width
      Width of the generated image.
    • $height
      Height of the generated image.

Retrieving image data

The following public methods for retrieving image related data are available:

Combining images

Scaling strategies

Rendering the image

The Color object

The Color object is merely a data container for defining color values to be used within the PHP_Image package. It comes with a set of setters and getters for setting and retrieving color and alpha channel data.


The constructor takes 4 parameters which are all optional:

Configuring the color

Retrieving color data

Validating color data

The Image/Text/Generic object

The Image/Text/Generic object is a generic text rendering object which can be extended with additional functionality using decorators.


The constructor takes 1 optional parameter:

Configuring the text

Retrieving text data

Rendering the text

The Image/Text/Decorator object family

The Image/Text/Decorator object family contains decorators for text rendering objects which add additional functionality to the Image/Text/Generic object or other objects implementing the Image\Text\Text interface.

Since they wrap around any Image\Text\Text implementation which could also be another Image/Text/Decorator instance, they share all methods of the decorated object and might also define their own.


The constructor depends on the specific Image/Text/Decorator implementation but usually takes at least one parameter which is the object to decorate:

Retrieving text decorator data

Rendering text using a decorator

Since all decorators implement the same interface as the standard Image/Text/Generic object, rendering using decorated text objects works the same way as rendering using non-decorated objects:

The Image/Text/Decorator/Border object

The Image/Text/Decorator/Border object is a decorator for text rendering objects which adds a simple border to the rendered text.

Configuring the border

Retrieving border data


See LICENSE.txt for full license details.