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
composer require atelier/rasterizerRequires PHP 8.3 or later, plus one rasterizer binary on the host:
brew install resvg # macOS
apt install librsvg2-bin # Debian, UbuntuOther platforms, package sources, and the binaries' own licences are in Installation.
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.
| 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.
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 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.
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.
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.
- 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.
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 PHPUnitChanges to public behaviour need a test and a documentation update.
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.
Atelier Rasterizer is released under the MIT License.