Quick Start

Everything goes through the Svg facade. Three ways in:

use Atelier\Svg\Svg;

Svg::create(800, 600)      // new document
Svg::load('icon.svg')      // from file
Svg::fromString($markup)   // from string

All three return the same Svg object with the same fluent API.

Create

Build a document from scratch with Svg::create(). Methods chain:

$svg = Svg::create(400, 300)
    ->rect(0, 0, 400, 300, ['fill' => '#0f172a'])
    ->circle(200, 150, 80, ['fill' => '#6366f1'])
    ->text(200, 240, 'Hello', ['text-anchor' => 'middle', 'fill' => '#fff', 'font-size' => '18'])
    ->save('output.svg');

Available shape methods: rect, circle, ellipse, line, path, polygon, polyline, text, image. Each takes coordinates then an optional attributes array.

Load and query

Load an existing file, then query elements with CSS selectors:

$svg = Svg::load('icons/arrow.svg');

// Single element
$svg->querySelector('path')?->setAttribute('fill', 'currentColor');

// All matching elements: returns ElementCollection
$svg->querySelectorAll('[fill="#000000"]')
    ->fill('currentColor');

$svg->save('icons/arrow.svg');

querySelectorAll() returns an ElementCollection. It supports fill(), stroke(), strokeWidth(), opacity(), setAttribute(), addClass(), each(), and more.

Optimize

Every Svg instance has optimize methods built in:

// Default preset: balanced
Svg::load('input.svg')->optimize()->save('output.svg');

// For web delivery: strips metadata, merges paths
Svg::load('input.svg')->optimizeWeb()->save('output.svg');

// Maximum compression
Svg::load('input.svg')->optimizeAggressive()->save('output.svg');

See Optimization for custom pipelines and all presets.

Sanitize user uploads

Before storing or rendering SVGs from untrusted sources:

$clean = Svg::fromString($userUpload)
    ->sanitize()   // removes scripts, event handlers, javascript: URLs
    ->toString();

See Document: Sanitization for strict and permissive profiles.

Output

$svg->toString();        // compact string
$svg->toPrettyString();  // indented string
$svg->save('out.svg');   // compact file
$svg->savePretty('out.svg'); // indented file
$svg->toDataUri();       // data:image/svg+xml;base64,...

echo $svg;               // same as toString()

Common patterns

Embed an image

Embed a raster image inside an SVG canvas. See Elements: Shapes.

<?php
Svg::create(400, 300)
    ->image('photo.jpg', 0, 0, 400, 300)
    ->save('output.svg');

Organize with defs and groups

defs() opens a <defs> block for reusable assets. group() returns the underlying Builder for nesting. See Elements: Structure.

<?php
$builder = Svg::create(200, 200)->defs()->group();
$builder->circle(100, 100, 50)->attr('id', 'dot')->end();

Linear and radial gradients

Define gradients inside <defs>, then reference them by ID. See Elements: Gradients.

<?php
Svg::create(200, 200)
    ->defs()
    ->linearGradient('grad', 0, 0, 1, 0)
    ->radialGradient('glow', 100, 100, 80)
    ->save('output.svg');

Error handling

Svg::load() and Svg::fromString() throw two exception types:

Atelier\Svg\Exception\RuntimeException: file not found, unreadable, or write failure
Atelier\Svg\Exception\ParseException: invalid XML or missing root <svg> element

Both extend \RuntimeException and implement Atelier\Svg\Exception\SvgExceptionInterface.

<?php
use Atelier\Svg\Svg;
use Atelier\Svg\Exception\ParseException;
use Atelier\Svg\Exception\RuntimeException;

try {
    $svg = Svg::load('upload.svg');
} catch (RuntimeException $e) {
    // File missing or unreadable
    echo 'File error: ' . $e->getMessage();
} catch (ParseException $e) {
    // Not valid SVG XML
    echo 'Parse error: ' . $e->getMessage();
}

For stricter parse control: such as failing on malformed but technically loadable files: use DomParser directly with ParseProfile::STRICT. See Document: Parsing.