PHP binding for libvips

php-vips is a binding for libvips for PHP 7.

libvips is fast and needs little memory. The vips-php-bench repository tests php-vips against imagick and gd. On that test, and on my laptop, php-vips is around four times faster than imagick and needs 10 times less memory.

Programs that use libvips don't manipulate images directly, instead they create pipelines of image processing operations starting from a source image. When the pipe is connected to a destination, the whole pipeline executes at once and in parallel, streaming the image from source to destination in a set of small fragments.

This module builds upon the vips PHP extension:

https://github.com/libvips/php-vips-ext

You'll need to install that first. It's tested on Linux and macOS --- Windows would need some work, but should be possible.

See the README there, but briefly:

1. Install the libvips library and headers. It's in the linux package managers, homebrew and MacPorts, and there are Windows binaries on the vips website. For example, on Debian:

   sudo apt-get install libvips-dev
   

   Or macOS:

   brew install vips
   

2. Install the binary PHP extension. You'll need a PHP development environment for this, since it will download and build the sources for the extension. For example, on Debian:

   sudo apt-get install php-pear
   

   Then to download and build the extension it's:

   pecl install vips
   

   You may need to add extension=vips.so or equivalent to php.ini, see the output of pecl.

3. Add vips to your composer.json:

     "require": {
       "jcupitt/vips" : "1.0.7"
     }
   

Example

#!/usr/bin/env php
<?php
require __DIR__ . '/vendor/autoload.php';
use Jcupitt\Vips;

// fast thumbnail generator
$image = Vips\Image::thumbnail('somefile.jpg', 128);
$image->writeToFile('tiny.jpg');

// load an image, get fields, process, save
$image = Vips\Image::newFromFile($argv[1]);
echo "width = $image->width\n";
$image = $image->invert();
$image->writeToFile($argv[2]);

Run with:

$ composer install
$ ./try1.php ~/pics/k2.jpg x.tif

See examples/. We have a complete set of formatted API docs.

Introduction to the API

Almost all methods return a new image as the result, so you can chain them. For example:

$new_image = $image->more(12)->ifthenelse(255, $image);

will make a mask of pixels greater than 12, then use the mask to set pixels to either 255 or the original image.

Note that libvips operators always make new images, they don't modify existing images, so after the line above, $image is unchanged.

You use long, double, array and image as parameters. For example:

$image = $image->add(2);

to add two to every band element, or:

$image = $image->add([1, 2, 3]);

to add 1 to the first band, 2 to the second and 3 to the third. Or:

$image = $image->add($image2);

to add two images. Or:

$image = $image->add([[1, 2, 3], [4, 5, 6]]);

To make a 2 x 3 image from the array, then add that image to the original.

Almost all methods can take an extra final argument: an array of options. For example:

$image->writeToFile("fred.jpg", ["Q" => 90]);

php-vips comes with full API docs. To regenerate these from your sources, type:

$ vendor/bin/phpdoc

And look in docs/.

There are around 300 operations in the library, see the vips docs for an introduction:

https://libvips.github.io/libvips/API/current

How it works

The vips extension defines a simple but ugly way to call any libvips operation from PHP. It uses libvips' own introspection facilities and does not depend on anything else (so no gobject-introspection, for example). It's a fairly short 1,600 lines of C.

This module is a PHP layer over the ugly vips extension that tries to make a nice interface for programmers. It uses __call() and __get() to make all libvips operations appear as methods, and all libvips properties as properties of the PHP Vips\Image class.

Test and install

$ composer install
$ composer test
$ vendor/bin/phpdoc

Regenerate auto docs

$ cd src
$ ../examples/generate_phpdoc.py