README

Rasterize SVG to PNG, JPEG or WebP from PHP, through a rendering binary you choose.

A typed PHP abstraction over a rasterizer binary. It does not render SVG itself, and that is the point: rendering SVG correctly is a browser-sized problem, so this package delegates it to resvg or rsvg-convert and gives you a stable API on top.

Rasterizer::create()->rasterize($svg, new BitmapOptions(width: 1200))->save('card.png');

Input is markup, any \Stringable such as an atelier/svg document, or an SvgInput built from a file or a stream. Nothing here depends on atelier/svg. Backed by an extensive test suite and PHPStan at its highest level.

Adapters · Options · Input · Failure · Testing · Documentation

Installation

composer require atelier/rasterizer

Requires PHP 8.3 or later, plus one rasterizer binary on the host:

brew install resvg          # macOS
apt install librsvg2-bin    # Debian, Ubuntu

Other platforms, package sources, and the binaries' own licences are in Installation.

Quick start

use Atelier\Rasterizer\Bitmap\BitmapOptions;
use Atelier\Rasterizer\Rasterizer;

$bitmap = Rasterizer::create()->rasterize($svg, new BitmapOptions(
    width: 1200,
    height: 630,
    keepAspectRatio: true,
));

$bitmap->save('card.png');

Rasterizer::create() picks the first adapter available on the host. See Usage.

Adapters

Adapter	Binary	Selected by
resvg	`resvg`	`Rasterizer::resvg()`
rsvg-convert	`rsvg-convert`	`Rasterizer::rsvgConvert()`

create() tries them in that order and returns the first one it finds, which is convenient in development and unpredictable in production. Naming the adapter explicitly is what makes output reproducible across machines, because two renderers do not agree on every edge case.

Adapters implement RasterizerInterface, so a third one is a class rather than a fork. See Adapters.

Options

BitmapOptions is a single immutable value: format, width, height, keepAspectRatio, scale, background, and timeout.

Give one dimension and the other follows the SVG's ratio. Give both, and keepAspectRatio (on by default) fits the drawing inside that box rather than distorting it. See Options.

Input and output

Input is whatever you already have:

use Atelier\Rasterizer\Svg\SvgInput;

SvgInput::fromString($markup);
SvgInput::fromFile('logo.svg');
SvgInput::fromStream($handle);

Output is a BitmapResult carrying contents, format, width, height and mimeType, so it can go to a file, a response, or object storage without touching the disk. Formats are PNG, JPEG and WebP, subject to what the selected adapter supports.

When it fails

Rasterizing shells out, which means it can fail in ways pure PHP cannot: a missing binary, a non-zero exit, a timeout, an unsupported format. Each is a typed exception rather than a false, and timeout is an option because a runaway render is a production incident.

Testing

Tests that shell out to a binary are slow and depend on the host. The package documents how to substitute an adapter so a consumer's own suite does not need resvg installed. See Testing.

Documentation

Installation: the binaries, per platform, and their licences.
Usage: input forms, options, and the result.
Adapters: what each one supports, and writing a third.
Options: every field, its default, and its bounds.
Testing: rasterizing in a suite without the binary.

The full documentation is published at ateliersvg.com/rasterizer.

Contributing

Contributions are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request.

Before submitting code, run:

composer qa   # PHP-CS-Fixer, PHPStan at level max, and PHPUnit

Changes to public behaviour need a test and a documentation update.

Support

Bug reports, security disclosures, and contribution guidelines are collected at ateliersvg.com/support.

Atelier is maintained by Simon André. Sharing the package or starring it on GitHub helps more than you would think.

License

Atelier Rasterizer is released under the MIT License.

atelier / rasterizer

Maintainers

Package info

Fund package maintenance!

Statistics

Security