Skip to content

Diagnostics

Jump to bottom
Jan Hermann edited this page Oct 9, 2026 · 1 revision

🔍

What the running PHP can do with images, the Imagine driver factory and exceptions.

Environment

Final class that knows which PHP image extensions are loaded and which formats they write. It is the only place that looks at the extensions. Drivers are tried in the order imagick, gd.

  • Environment::current(): shared environment of the running PHP.
  • Environment::setCurrent(?Environment $environment): replaces the shared environment (for tests), null resets it.
  • Environment::probe(): array: list of DriverInfo of the running PHP.
  • new Environment(?array $drivers = null): describes the drivers by hand, the running PHP is probed when null.
  • drivers(): array: drivers in order of preference.
  • firstAvailable(): ?string: name of the preferred loaded driver.
  • firstSupporting(Format $format): ?string: name of the preferred driver which can write the format.
  • explain(?Format $format = null): string: explains what is missing and how to fix it (packages, configure flags).

DriverInfo

Readonly class with name (imagick or gd), available, version and formats (can the driver write webp / avif). supports(Format $format): bool tells if the driver is available and writes the format.

ImagineFactory

Provides the Imagine driver: Imagick when available (better AVIF/WebP support), GD otherwise. When a format is requested, the first driver which can write it is used. Drivers are created once.

  • ImagineFactory::create(?Format $format = null): ImagineInterface
  • ImagineFactory::supportsFormat(Format $format): bool
  • ImagineFactory::assertSupports(Format $format): void
use Imagony\Converters\Format;
use Imagony\ImagineFactory;

$image = ImagineFactory::create(Format::AVIF)->open("photo.jpg");

Exceptions

All exceptions implement the marker interface ImagonyException, so they can be caught together.

  • NoDriverException: neither GD nor Imagick is available. It is always thrown.
  • UnsupportedFormatException: a format is requested, but no available driver can write it. Has the public property format and a message with the cause and the fix, e.g. GD 2.1.0: built without AVIF. Rebuild PHP's GD with --with-avif ....

UnsupportedFormatException is thrown by Thumbnail::create() only in strict mode: strict: true always throws, strict: false only logs a warning once, strict: null (default) follows kernel.debug.

An image which can not be read or written (a corrupt file, no write permission for folder) is replaced by the fallback image and logged as a warning.

Picture

Helper class with static checks of image files.

  • Picture::exists(string $filename): bool: the file exists and is a regular file.
  • Picture::isValid(string $filename): bool: the file exists and can be opened as an image by Imagine.

Requirements

GD or Imagick is required (Composer suggests them only). WebP and AVIF depend on how PHP was built:

Extension WebP AVIF
GD built with --with-webp (libwebp-dev) built with --with-avif (libavif-dev), PHP 8.1+
Imagick ImageMagick with the libwebp delegate ImageMagick with the libheif/libavif delegates

Docker example for GD with both formats:

RUN apt-get update && apt-get install -y libwebp-dev libavif-dev libjpeg-dev libpng-dev libfreetype6-dev
RUN docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp --with-avif && docker-php-ext-install gd

Clone this wiki locally