Sheath Statamic Laravel Package

Getting Started

1. composer require fortephp/sheath-statamic (pull in fortephp/sheath too if it isn't already a transitive dependency).
2. Laravel package discovery registers the service provider automatically — open it first. It's the fastest way to see exactly what the package contributes to Statamic (Antlers-side registration and the diagnostics/region-syntax hooks) before you read any prose docs.
3. Skim the repo README for the canonical Antlers call signature, then do one concrete thing: convert a single repeated Antlers partial into a Sheath component and render it from one template. Keeping the first conversion small makes it obvious whether a problem is your component, your data, or Antlers' parse order.

Version note for this release: v0.1.1 is a diagnostics-only fix (false Antlers region syntax reports). It changes nothing at runtime, so it is a safe bump on an existing install and the recommended starting version for new ones. If you installed 0.1.0 and your editor/tooling warned about region syntax in Antlers files that rendered fine, upgrading is the fix.

Implementation Patterns

• Wrap, don't rewrite. Keep existing Antlers templates as the entry point and have them delegate to a Sheath component. This lets you migrate a page section at a time and keeps Statamic's routing/entry data flow untouched.
• One component = one visual unit. Because the component owns its own data contract, resist passing whole entry objects through; map to scalars/collections at the Antlers boundary so the component stays testable outside Statamic.
• Treat regions as the public API. Named regions/slots are what template authors will edit. Document them next to the component and consider them semver-relevant — renaming a region is a breaking change for content templates, not just code.
• Data from Antlers, logic in PHP. Antlers modifiers are seductive inside component calls; prefer computing derived values in the component (or a view model) so the behavior is unit-testable and greppable.
• Colocate in resources/views/components (or whatever path the README specifies) and instantiate them from partials rather than from many entry templates — one indirection point makes future refactors cheap.
• CI integration. Run your template/component tests plus a render smoke test of one real Antlers template in CI. Because this package sits between two moving parts (Sheath and Statamic), a smoke test catches integration breakage that unit tests won't.

Gotchas and Tips

• 0.x versioning. Pre-1.0, minor bumps may carry breaking changes. Pin with ~0.1.1 or a lockfile, and read the changelog on every upgrade. v0.1.1 itself is patch-level and safe.
• Diagnostics are advisory. The region-syntax diagnostics fixed in this release are tooling output, not runtime validation — a diagnostic warning never meant your template was broken at render time. Don't "fix" templates to silence diagnostics without confirming the rendered output; conversely, a clean diagnostics run doesn't prove a template renders.
• After upgrading, restart your editor/language server. Diagnostics are usually cached in the editor session, so stale false positives can survive a composer update. Clear caches too: php artisan view:clear, and php artisan statamic:stache:clear if content-side changes aren't visible.
• Compiled-view staleness is the #1 false bug report. When a component change doesn't show up, run php artisan view:clear before debugging anything else. php artisan view:cache deliberately surfaces compile-time errors early — useful in CI, annoying locally.
• Antlers parse order and whitespace control bite when components emit markup adjacent to Antlers conditionals. If output looks mangled, isolate the component in a bare template with hardcoded data to determine whether Antlers or the component is responsible.
• Extension points to know: the package's service provider is where you'd override bindings or register custom behavior; if the diagnostics layer is configurable, that config is worth reading before you disable editor tooling wholesale to stop noise.
• Upgrade triage for this release: if you saw region-related warnings on 0.1.0, bump to 0.1.1 and re-check the same templates. If warnings persist, they're a genuine report — file an issue with a minimal Antlers snippet rather than working around it.