Social Images Statamic Laravel Package

Getting Started

This package generates social share images (OG images) from code templates rendered in headless Chrome. To get productive quickly:

1. Require the package and its core dependency (social-images-core >= 1.1.1 for the v1.1.2 fixes).
2. Publish config and any assets, then confirm a Chrome/Chromium binary is available to the renderer (Browsershot/puppeteer-style dependency). On servers, this is usually the first failure point.
3. Define a template — typically an Antlers/Blade view — with the dimensions and placeholders you need (title, image, logo, background).
4. Wire one entry or model to it and generate an image manually before automating. Use the package’s storage disk config to control where generated images land and how they are served.

The first real use case is usually: “when an entry is saved, generate a 1200×630 image from its title/hero image, store it on the public disk, and expose the URL to meta tags.” Start with a single template and one model before rolling it across collections.

Pay attention to the package docs on code templates and remote assets — v1.1.2 restores the ability to load stylesheets, fonts, and images from URLs via social-images-core 1.1.1. If you were blocked by the 1.1.0 regression, upgrading is the first step.

Implementation Patterns

Template-per-context. Keep templates small and purpose-built: one for articles, one for products, etc. Use Antlers partials for shared layout and pass only the data the template needs. This keeps Chrome renders fast and makes escaping easier to reason about.

Generate via queue. Rendering is I/O- and CPU-heavy. Dispatch generation to a queue job on model save or via an event listener. This also lets you retry transient Chrome/network failures without blocking the request. Monitor job status — v1.1.2 fixes a bug where a render that waited out a rate limit and then failed permanently still appeared queued for roughly a minute, so upgrade if you rely on status polling.

Regenerate on content changes. Hook into saved/updated events and regenerate only when relevant fields change. For bulk backfills, provide an artisan command or use the package’s import/export facilities (the core 1.1.1 release includes import/export fixes). Avoid queuing thousands of renders without rate limiting.

Use remote assets deliberately. Since code templates can again load remote CSS, fonts, and images, prefer absolute URLs and stable CDNs. This is convenient for brand fonts and backgrounds, but treat every remote URL as server-side input: Chrome fetches it from your server, not the visitor’s browser.

Integrate with meta tags. Store the generated path/URL on the model or in a predictable convention (social/{model}/{id}.png), then reference it in your layout’s og:image and twitter:image tags. Add a fallback image for models that have not been generated yet.

Testing and local development. Provide a fake/disabled renderer in local/testing environments where Chrome is unavailable, or point the package at a locally installed Chromium. Snapshot or smoke-test one template render in CI if Chrome is available; otherwise assert that jobs are dispatched with the right payload.

Gotchas and Tips

Escape untrusted content in templates. The v1.1.2 documentation explicitly warns that code templates are opened by Chrome on your server and Antlers does not escape by default. Any user-supplied value — titles, names, descriptions, imported content — must be escaped or sanitized before interpolation. Use Antlers escaping/sanitizing modifiers and avoid injecting raw HTML from untrusted sources. This is both an XSS and an SSRF-adjacent risk because Chrome will fetch URLs present in the rendered page.

Remote assets can fail silently or noisily. If a font or image URL is unreachable from the server, Chrome may render a fallback or time out. Test templates with network access from the same environment as production. Watch for CORS, authentication, and firewall rules; Chrome runs server-side and does not share the visitor’s network context.

Rate limits and retries need observability. After upgrading to v1.1.2, a render that exhausts retries should move to a failed state promptly instead of lingering as queued. Still, log rate-limit responses and failed jobs; do not assume a queued status means progress. Ensure queue workers are running and that retry/backoff settings match the external service’s limits.

Chrome in server environments is fragile. Common issues: missing shared libraries, sandbox restrictions, low /dev/shm, and font availability. If renders fail only in production, check the Chrome binary path and launch flags first. Container images often need --no-sandbox and a larger shared memory setting.

Clear caches after config or template changes. Laravel config caching and any view/template caches can mask changes. After adjusting disks, Chrome paths, or template locations, run the relevant clear commands and restart queue workers.

Storage and URL correctness. Generated images must be written to a disk that is publicly served or synced to your CDN. A common bug is generating successfully but exposing a local path instead of a public URL. Verify the stored path, disk visibility, and APP_URL in non-local environments.

Upgrade the core dependency together. v1.1.2’s template asset loading and import/export fixes live in social-images-core 1.1.1. If you pin the core package independently, confirm it is at least 1.1.1; otherwise you may retain the 1.1.0 regression where remote stylesheets, fonts, and images stop loading.