How to use Vips for faster image rendering

Overview

Your Neos website or Flow application usually uses ImageMagick and GD for rendering smaller versions of your photos, or previews of other media assets. While these libraries are quite powerful, they need a big amount of memory for processing images. It can easily happen for a Neos page with a lot of thumbnails to consume hundreds of Megabytes of RAM to create the respective image files. When the original assets are rather large or you need to process animated GIFs, you might even need Gigabytes of RAM just for rendering that page.

Fortunately, Beach provides libvips, a low-level code library which can do almost the same things like ImageMagick, but much faster and with a relatively small memory footprint. Yet more fortunately, Neos and Flow do support libvips through jcupitt/vips, with just a little configuration.

We recommend that you configure all your Flow and Neos projects to use Vips instead of ImageMagick.

Before you start

When you enable Vips for your project, you will also need Vips support in your development environment.

The reason for that is, that you need to be able to run composer update. The package which provides Vips support (rokka/imagine-vips) has a dependency on the vips PHP extension, and if you don't have that extension enabled, Composer will complain about non fulfilled platform requirements.

The solution is easy though: just install PHP Vips for your local environment. Make sure though, that everybody in your team who runs composer update also has Vips installed.

Installing PHP Vips for your development environment

For your development environment you need to install two libraries:

1. a Vips library for your operating system
2. a PHP extension which provides bindings to that low-level library

The installation process is explained on the php-vips-ext project site on Github. As an example, if your development system is a Mac and you are using Homebrew as a package manager the installation steps are as follows:

First install the libvips system library:

When everything's working fine, you should be able to see vips in the list of enabled PHP modules when you're running php -m from the command line.

If that does not list vips, you need to enable the extension in your PHP configuration, for example by creating a new file ext-vips.ini in your PHP's conf.d/ folder:

Enabling Vips for Flow and Neos

You can enable Vips for your project with just two steps:

1. include the rokka/imagine-vips library into your Composer dependencies
2. configure Neos.Media to use Vips instead of ImageMagick

Install the needed packages

Start by adding the Composer dependency:

Important: As of version 2, the  jcupitt/vips package (a transitive dependency of the rokka/imagine-vips package) uses the FFI of PHP.

Since that is not enabled on Beach (as the PHP manual says: FFI is dangerous, since it allows to interface with the system on a very low level), you may also need to pin that package to the 1.x line with the following command. Otherwise you may end up updating your composer.lock on a machine that has FFI enabled, leading to errors after deployment on Beach.

Configure your project

Then add the following configuration to your settings. We recommend that you create a Settings.yaml for the Beach context in your global configuration. That way you can work with ImageMagick or GD in your local development setup and automatically use Vips in your Beach instance.

Create a file Configuration/Production/Beach/Instance/Settings.yaml and add the following content:

The driver setting in line 3 will enable Vips as the default driver for all image processing. As a fallback we also still allow GD and ImageMagick. The setting in line 15 is a bit of a workaround: Vips does not support creating interlaced images and if this setting is filled with anything else than null, the Imagine Vips library will complain with an exception.

Checking that Vips is working fine

When you followed the steps above, commit the result (as always, don't forget to commit your composer.lock file) and deploy to Beach. You can check if your configuration is working properly by looking for the setting in the Neos configuration module or by showing the settings from the command line: