Blade Directives Laravel Package

Technical Evaluation

Architecture fit edalzell/blade-directives (published as statamic-blade) is a Statamic addon that bridges Statamic's Antlers-first rendering model into Laravel's Blade compiler. Architecturally it is a thin, idiomatic Laravel package: a service provider registers custom Blade directives that proxy into Statamic's content/rendering APIs. For a team standardized on Laravel + Blade, this is a natural seam — it lets Blade templates call into Statamic without forcing Antlers syntax into the view layer. The fit is strongest when Statamic is already the CMS and the application layer is conventional Laravel (controllers, Blade views, Livewire components). It is a poor fit if the team is committed to Antlers, or if views are rendered by Inertia/Vue where Blade directives have no runtime.

Integration feasibility Low effort to install (Composer + provider auto-discovery), but the real feasibility question is directive coverage and version alignment. Expect to spend a spike validating: (a) which directives the package actually exposes, (b) whether they resolve against the Statamic version in use, and (c) whether composed output (nested Antlers inside Blade, or Blade inside Antlers) round-trips cleanly. The lack of stars and dependents means there is no community-validated compatibility matrix — compatibility must be established by the team, not assumed.

Technical risk This is the dominant concern and should be surfaced to stakeholders plainly: a single-maintainer, near-zero-adoption package sitting in the critical rendering path. Risks ranked:

• Abandonment / bus factor of one. No dependents and no visible adoption signal means no downstream pressure to keep it current with Statamic releases.
• Version drift. Statamic's rendering APIs have moved across major versions; a thin directive shim is exactly the layer most likely to break silently on upgrade.
• Opaque failure modes. Directives fail at render time, often inside cached views, so a broken directive can surface as a blank page rather than a stack trace.
• Security surface. Directives that render user-influenced Antlers strings are an injection vector if inputs are not constrained.

Key questions

1. Exactly which directives ship, and which of our required content types (Bard, Markdown, collections, globals, forms) do they cover?
2. What Statamic and Laravel version ranges are pinned in composer.json, and are they still resolvable?
3. Is the package's test coverage sufficient for us to fork and maintain it if the author stops?
4. Does directive output participate correctly in Statamic's view caching and Laravel's view:cache?
5. What is the fallback path — Antlers, or native Statamic Blade support in newer releases — if we adopt and later need to exit?

Integration Approach

Stack fit Assumes Laravel (8/9/10-era) with Statamic 3/4 installed and Blade as the view engine. If the project already mixes Antlers and Blade, this package is additive and non-invasive. If the project is Antlers-only, adopting it implies a deliberate decision to move view authoring to Blade — which is a team-skills decision as much as a technical one. Confirm the existing config/view.php and Statamic's view resolution before assuming directives will be picked up in every template context (e.g., Statamic's control-panel views vs. app views).

Migration path Incremental and reversible, which is the package's main strategic value:

1. Install in a dev branch, register the provider, and prove a single directive in a scratch view.
2. Convert one low-risk page from Antlers to Blade, using directives only for content retrieval.
3. Hold at partial migration — Antlers for editor-facing templates, Blade for app-owned views — until confidence is established.
4. Only then expand to high-traffic templates, with a parallel Antlers version kept until the Blade version is verified in staging.

Compatibility Treat version pinning as a gating item. Verify the package's composer.json constraints against the target Statamic and Laravel versions before any code is written; a constraint mismatch means either an upgrade of unrelated dependencies or a fork. Also validate against PHP minor versions used in CI and production, and confirm behavior under php artisan view:cache and Statamic's static caching.

Sequencing Spike (1–2 days) → compatibility verdict → isolated page conversion → staging validation → production rollout page-by-page. Do not sequence this concurrently with a Statamic major upgrade; isolating variables matters more here than velocity, given the thin maintenance base.

Operational Impact

Maintenance Effectively self-maintained. Plan for the package to be vendored or forked into the org's namespace the moment it becomes load-bearing. Budget a recurring line item (a few hours per Statamic upgrade) to re-verify directives, and add a smoke test that renders a page exercising every directive in use.

Support GitHub issues only, best-effort, no SLA and no commercial backing. Escalation path is internal: whoever forked it. This must be an explicit, accepted trade-off — it is not a "supported dependency" in any procurement sense.

Scaling Directive expansion happens at Blade compile time, so runtime cost is negligible once views are cached; the concern is cache invalidation correctness. Under Statamic static caching or Laravel's view cache, a directive whose output depends on request or user context can be cached incorrectly. Load characteristics are therefore fine; correctness under caching is the scaling question.

Failure modes

• Directive throws → uncaught render exception → 500 on an otherwise healthy page.
• Silent no-op if the provider is not registered in a given context (queue workers, console-rendered mail) — output appears empty rather than erroring.
• Version drift after a Statamic upgrade → directives resolve to stale APIs.
• Cache poisoning: context-dependent output baked into a cached view. Mitigations: wrap high-risk directives in a defensive Blade component, add a render smoke test to CI, and pin the package to an exact version.

Ramp-up Low for anyone fluent in Laravel Blade and Statamic content APIs; moderate for Antlers-only developers, who must learn Blade syntax and the directive surface simultaneously. Recommend a short internal write-up of the supported directives and the approved usage patterns — the package's own documentation is unlikely to be comprehensive. Given zero dependents, plan for the team, not the community, to be the source of truth.