Statamic Content Renderer Laravel Package

Getting Started

• Install with composer require visuellverstehen/statamic-content-renderer, then publish the config: php artisan vendor:publish --tag=statamic-content-renderer-config.
• Look first at config/statamic-content-renderer.php — that file is the contract for how Bard/Replicator set types map to Blade views or renderer classes. The README's config example is the fastest way to understand the shape; the package source (src/) is small enough to read end-to-end in one sitting.
• First use case: you have a headless/API-driven setup (or a Laravel app reading Statamic content from a separate install) and you receive a Bard field value as a plain array of ProseMirror nodes. You want HTML out of it in a Blade view without booting Statamic's full augmentation stack. Configure one set type, render one field, confirm the HTML, then expand.
• Start with a single simple set (one text field, one view) before wiring up nested sets — the config structure makes much more sense once you've seen one round-trip working.

Implementation Patterns

• Wrap the renderer in a dedicated class. Don't call the package directly from Blade in more than one or two places. Inject it into a small ContentRenderer/HtmlRenderer service of your own, so that when set definitions change you have one seam to update and one place to add caching.
• Keep set config next to the fieldset. The set keys in your package config must mirror the set handles declared in the Statamic fieldset. When they drift, rendering degrades silently (empty strings) rather than throwing — so co-locate them or generate one from the other.
• View-per-set is the pragmatic default. For each set, point the config at a Blade view and pass through the set's fields. Reserve custom renderer classes for sets that need lookups (related entries, asset URLs) or non-trivial logic.
• Render at the edge, cache the result. Content renderers are pure array→HTML functions, which makes them ideal cache targets. Cache keyed on the entry ID + updated_at (or the content hash), not on the request, and you get cheap invalidations for free. This matters most when the source of truth is a remote Statamic API and every render is a round-trip.
• Feed it augmented data where possible. If relations (assets, entries, terms) need resolving, augment upstream — via Statamic's REST API ?augmented=true, or by resolving IDs yourself — before handing the array to the renderer. The renderer renders what it's given; it won't chase relationships.
• Test with fixture JSON. Capture a real Bard payload into tests/fixtures/*.json and assert on rendered output. This is the single highest-value test you can write for this package, because config drift is the main failure mode and fixtures catch it immediately.
• Compose with your own middleware/pipeline for post-processing (e.g. adding anchor IDs to headings, lazy-loading images, rewriting internal links). Do that outside the renderer rather than by overriding set views.

Gotchas and Tips

• Pin to >=2.0.1. 2.0.1 fixes missing set indexes in Bard content rendering — sets nested inside Bard content could render without their index resolved. If you're on 2.0.0 and seeing sets that render partially, render the wrong view, or come out empty while top-level Replicator sets work fine, that's the bug. Upgrade before debugging your config.
• Set indexes are positional. The mapping is index-based, so reordering sets in the fieldset (or in your config array) without updating the other side is a silent breakage. Treat the config as schema, review it in PRs, and avoid associative-key shortcuts.
• Nested sets need nested config. A Replicator inside a Bard set (or a Bard inside a Grid) requires its own mapping at that level; a flat config will render the outer set and drop the inner content. The 2.0.1 fix is a reminder that nesting is where this package is most fragile.
• Silent failures are the default. Missing views, unmatched set types, and null field values generally produce empty output rather than exceptions. When something doesn't render, check in this order: (1) is this the augmented payload or raw? (2) does the set type/_id match a config key exactly? (3) does the view path resolve? Add a temporary Log::debug() in your renderer wrapper to dump the incoming node types.
• Escape deliberately. Set views output HTML from content authors; use {!! !!} in the places you intend and make sure any user-supplied or API-sourced attributes are escaped. The renderer won't do this policy for you.
• Config caching bites during development. After editing the config mapping, php artisan config:clear — a stale cached config is an easy 20 minutes lost, and the symptom (old set behaviour) looks identical to a renderer bug.
• Extension points worth knowing: the config file itself (set → view/class mapping), the view namespace for overriding shipped views, and the ability to swap in your own renderer class for a set type. Prefer these over forking — the package is small and a fork will cost you the 2.0.1-style fixes.
• Version note: 2.0.x is a major line; if you're migrating from 1.x, re-check the config format and any renderer interfaces you implemented, since the set-index handling is part of that redesign.