Image processing

• Usage
  • Image information
    • Inspectors
  • Image manipulation
  • Image metadata
    • XMP
      • Reading
  • Value objects
    • Color
    • Dimensions
    • Font
    • Point
    • Points

The pixel library allows you to manipulate images through a consistent API using either GD or ImageMagick. GD generally provides faster processing for many operations and is available in most PHP installations, while ImageMagick offers more advanced image processing capabilities and better support for complex formats such as animated GIFs and multi-frame images.

Usage

First you'll have to decide whether to use GD or ImageMagick. In this example we'll use the ImageMagick processor.

$image = new ImageMagick('image.png');

// You can also create an instace from a path like this

$image = ImageMagick::fromPath('image.png');

// Or directly from a binary blob like this

$image = ImageMagick::fromBlob($blob);

// And finally from a stream

$image = ImageMagick::fromStream($stream);

Image information

The getMimeType method returns the mime type of your image.

$mimeType = $image->getMimeType();

The getHeight method returns the height of your image.

$height = $image->getHeight();

The getWidth method returns the width of your image.

$width = $image->getWidth();

The getDimensions method returns a Dimensions instance representing the dimensions of the image.

$dimensions = $image->getDimensions();

$width = $dimensions->width;
$height = $dimensions->height;

Inspectors

To retrieve more advanced image information you can use inspectors.

The TopColors inspector returns an array of the top n colors in an image, represented as Color class instances. By default, it returns the top five colors, but you can specify a custom number of colors to return.

$topColors = $image->inspect(new TopColors);

foreach ($topColors as $color) {
    var_dump($color->toHexString());
}

Here are all of the included image inspectors:

You can also create your own custom image inspectors by implementing the InspectorInterface.

/**
 * @implements InspectorInterface<Dimensions>
 */
class Dimensions implements InspectorInterface
{
	/**
	 * {@inheritDoc}
	 */
	#[Override]
	public function inspect(object &$imageResource): Dimensions
	{
		return new Dimensions(
            $imageResource->getImageWidth(),
			$imageResource->getImageHeight()
        );
	}
}

The generics annotation connects the inspector implementation with its return type. This allows your IDE and static analysis tools such as PHPStan to understand the value returned by inspect() and provide accurate type hints, auto-completion, and type checking.

Image manipulation

The apply method allows you to apply an image operation to your image.

$image->apply(new Sharpen);
$image->apply(new Border(new Color(0, 0, 0, 127), width: 10));

You can also pipeline multiple operations using the Pipeline class.

$image->apply(new Pipeline(
    new Sharpen,
    new Border(new Color(0, 0, 0, 127), width: 10),
));

The applyOnClone method allows you to apply an image operation to a copy of the image instance while leaving the original unchanged. Just like with the apply method, you can apply individual operations directly or use the Pipeline class to apply multiple operations.

$greyscaleThumbnail = $image->applyOnClone(new Pipeline(
    new Resize(new Dimensions(300, 300)),
    new Greyscale,
));

Here are all of the included image operations:

You can also create your own custom image operations by implementing the OperationInterface.

class MyOperation implements OperationInterface
{
    #[Override]
	public function apply(object &$imageResource): void
	{
        // Do your custom image operations here
    }
}

The toBlob method returns the raw binary image data.

$image = $image->toBlob();

// You can also tell it to return a different image type

$image = $image->toBlob('jpg');

// You can also adjust the image quality in percent (default is 95%)

$image = $image->toBlob('jpg', 70);

The toBase64 method returns a base64 encoded representation of the raw binary image data.

$image = $image->toBase64();

// You can also tell it to return a different image type

$image = $image->toBase64('jpg');

// You can also adjust the image quality in percent (default is 95%)

$image = $image->toBase64('jpg', 70);

The toDataUri method returns a data uri representation of the image.

$image = $image->toDataUri();

// You can also tell it to return a different image type

$image = $image->toDataUri('jpg');

// You can also adjust the image quality in percent (default is 95%)

$image = $image->toDataUri('jpg', 70);

// Display the image

echo "<image src='{$image}'>"; // <image src='data:image/jpeg;base64,...'>

The toStream method returns the image as a stream. By default, it uses StreamStorage::Temp, which creates a PHP php://temp stream. This stream stores data in memory until it reaches 2 MB before automatically spilling over to a temporary file on disk, providing a good balance between performance and memory usage. If you prefer to keep the entire stream in memory, pass StreamStorage::Memory, which creates a php://memory stream.

$stream = $image->toStream();

// You can also tell it to return a different image type

$stream = $image->toStream('jpg');

// You can also adjust the image quality in percent (default is 95%)

$stream = $image->toStream('jpg', 70);

// And as mentioned above you can choose which stream wrapper to use

$stream = $image->toStream(stream: StreamStorage::Memory);

As the name suggests the save method will save your edited image to disk.

// Override original file

$image->save();

// Create a new file

$image->save('edited_image.png');

// You can also adjust the image quality in percent (default is 95%)

$image->save('edited_image.png', 70);

Image metadata

The library also includes functionality for working with embedded image metadata.

XMP

Reading

The XmpReader class allows you to extract XMP metadata from the image file.

Note: The XMP reader relies on FFI and libexempi. The reader will attempt to auto-detect the shared library, but depending on your setup, you may need to specify it manually.

$reader = new XmpReader('image.tif');

// You can specify the shared library if needed

$reader = new XmpReader('image.tif', 'libexempi.so.8');

The toXml method returns all the XMP data as XML.

$xml = $reader->toXml();

// You can also cast the reader object to a string

$xml = (string) $reader;

The getProperties method returns all the XMP properties as objects.

$properties = $reader->getProperties();

// You can also select the properties from a specific namespace

$properties = $reader->getProperties('http://purl.org/dc/elements/1.1/');

The getProperty method allows you to get a specific property. The first parameter is the property namespace and the second is the property name.

$property = $reader->getProperty('http://purl.org/dc/elements/1.1/', 'title');

echo $property->value;

Value objects

Color

The Color class is a value object for representing colors. It is used by image operations and inspectors.

$black = new Color(0, 0, 0, 127);

// The color values can be accessed as read-only attributes

$red = $black->red; // 0
$green = $black->green; // 0
$blue = $black->blue; // 0
$alpha = $black->alpha; // 127 - defaults to 255

// A copy with modified values can be created using the "with" method

$green = $color->with(green: 255);

The following methods are available:

Dimensions

The Dimensions class represents the dimensions of an object in pixels. It is a read-only value object with two properties: width and height.

$dimensions = new Dimensions(100, 150);

$width = $dimensions->width; // 100
$height = $dimensions->height; // 150

Font

The Font class represents a font and is used by drawing operations.

$font = new Font('Arial.ttf', 14, new Color(255, 0, 0));

$path = $font->path; // Arial.ttf
$size = $font->size; // 150
$color = $font->color; // Color(255, 0, 0) - defaults to Color(0, 0, 0)

Font sizes are interpreted by the underlying rendering engine and may produce slightly different results between GD and ImageMagick.

Point

The Point class represents a 2D coordinate. It is a read-only value object with two properties: x and y.

$point = new Point(100, 150);

$x = $point->x; // 100
$y = $point->y; // 150

Points

The Points class represents an ordered collection of points. It is used by drawing operations to define shapes, lines, and paths. The class implements Countable and IteratorAggregate, allowing it to be counted and iterated over directly.

$square = new Points(
    new Point(0, 0),     // top-left
    new Point(100, 0),   // top-right
    new Point(100, 100), // bottom-right
    new Point(0, 100),   // bottom-left
);

foreach ($square as $point) {
    // ...
}

The following additional methods are available: