Product Decisions This Supports
- Feature: server-side generated visual assets. Enables OG/social share images, status badges, progress rings, sparklines, simple bar/donut charts, dynamic avatars/initials, certificates, and vector assets embedded in PDFs or emails — all produced from PHP without a Node/Chrome pipeline.
- Build vs. buy vs. outsource. Frames the real decision as a spectrum: (a) hand-rolled string templating, (b) a thin SVG builder like this package, (c) a headless-browser screenshot service (Browsershot/Puppeteer, ~100–300 MB image, per-request Chrome), or (d) a SaaS image API (Cloudinary/imgix/Bannerbear, per-image pricing plus vendor lock-in). This package sits at the low-cost, low-capability end and wins when output is geometric and template-driven.
- Infra cost curve. No headless Chrome fleet, no queue workers blocked on rendering, no external per-image billing. Output is deterministic text: cheap to generate, trivially CDN-cacheable, and diffable in code review.
- Roadmap sequencing. Appropriate as an enabling primitive for a v1 of "dynamic images" — ship badges/OG cards now, defer rich charting and raster export until a validated need appears. Also useful at build time: generating icon sprites, placeholders, and seed fixtures for design tokens.
- Scope boundary for design ops. Shifts repetitive variant production (sizes, colors, labels, localization strings) from designers to code paths, freeing design capacity for work that actually needs a human.
- Accessibility and i18n decisions. Forces an explicit call on
<title>/<desc>/role="img" and on text layout for translated strings — cheap now, expensive to retrofit.
When to Consider This Package
Adopt when most of these hold:
- You need programmatic SVG authored in PHP/Laravel, and the shapes are simple: rects, circles, lines, paths, text, groups, basic gradients.
- You want zero non-PHP runtime dependencies — no Node, no Chromium, no Java, no external API. Composer install plus the
dom/xml extensions is the whole footprint.
- Output is deterministic and testable: you want to assert exact markup in PHPUnit rather than eyeball PNGs.
- You are wrapping it behind an internal service/interface anyway, so the library's API surface is not spread across the codebase.
- Volume and complexity are modest — hundreds to low millions of small, cacheable assets.
Look elsewhere when any of these are true:
- Raster output is required (PNG/JPEG for platforms that reject SVG). SVG-only means you need a converter step — at which point compare against
spatie/image/Intervention Image or a real renderer.
- Accurate text layout matters: wrapping, measuring, font shaping, emoji, RTL, and CJK fallback are not what a markup builder gives you.
- You need pixel-perfect HTML-to-image fidelity (arbitrary CSS, web fonts, flexbox). That is a headless-browser problem; a builder will be re-implemented badly.
- Advanced SVG features are in scope: filters, masks, clip paths beyond basics, animation,
foreignObject.
- Maintenance posture is a gate for you. ~100 stars, last release March 2023, single maintainer, repository provenance unclear. Low churn is defensible for a stable format, but treat it as vendored-risk: pin the version, forbid direct use outside an adapter, and budget a half-day to fork if needed. If your org requires an actively maintained dependency with a security response process, prefer a maintained equivalent or ~200 lines of
DOMDocument in-house.
- Untrusted input reaches the output. The library builds markup; it does not sanitize. Any user-supplied string in a
<text> or attribute is an injection surface — sanitize and escape at the boundary or you have shipped an XSS vector.
How to Pitch It (Stakeholders)
For executives (one paragraph). We can generate our visual assets — social cards, badges, progress indicators, simple charts, certificates — directly from our existing PHP application, with no new infrastructure, no third-party image service, and no per-image fees. It removes a recurring dependency on design for routine variants and gives marketing/product self-serve control over localized and segmented creative. The trade-off is capability: it produces vector graphics from templates, not pixel-perfect renditions of arbitrary web pages, and the library itself is a small, slow-moving open-source project, so we will wrap it behind our own interface — roughly a day of engineering — so it can be replaced without touching product code. Recommendation: adopt for a scoped v1 behind an adapter, measure usage for a quarter, and revisit if we hit raster export or complex layout.
For engineering. It is a fluent builder over DOMDocument that emits SVG strings — no compile step, no extensions beyond dom. Wrap it in a single SvgFactory/SvgRenderer service, cache by a hash of the input payload, serve with long-lived cache headers, and validate the output with snapshot tests. Two hard rules: never interpolate raw user input into markup, and always emit role="img" with <title>/<desc>. Because the upstream is quiet (last release 2023, small community), pin the version in composer.json, keep it to one adapter file, and be prepared to vendor or fork — the API is small enough that replacement cost is measured in hours, not sprints. Watch one product-level caveat: SVG support in email clients and some social platforms is inconsistent, so confirm the target consumer accepts SVG before committing to it over PNG.