Sage Directives Laravel Package

Technical Evaluation

Package: log1x/sage-directives — a Blade directive library for Sage (Roots) WordPress themes, exposing WordPress and Advanced Custom Fields APIs as expressive template directives (@field, @image, @posts, @shortcode, @svg, etc.).

Architecture fit: Thin, additive adapter layer. It sits in the presentation tier of a Sage 10/11 theme (Acorn + Blade) and wraps existing WordPress/ACF functions rather than introducing new infrastructure. That makes it low-coupling and easy to reason about architecturally: no database footprint, no runtime services, no queue or storage concerns. It is not a general Laravel package — directives call global WordPress functions, so it is only viable inside a WordPress-bootstrapped Blade context.

Integration feasibility: High. Composer-installable, auto-discovered via Acorn's package manifest, no configuration required for the common directives. Requires ACF Pro for the field-oriented directives (a paid-license dependency that is frequently the real gating item, not the package itself). A Blade-fluent developer can integrate in an afternoon; effort concentrates in template refactoring rather than setup.

Release assessment (v2.0.7): Purely a patch. One functional bug fix — @image option parsing when arguments are empty strings, variables, or function calls — plus a docblock/typo correction and one first-time contributor. No new directives, no removed or renamed directives, no deprecations, no signature or output-contract changes beyond correcting malformed edge-case rendering. Semver-compatible with 2.x; drop-in for anyone on ^2.0. The fix itself is a reliability signal: it confirms the directive argument parser has had sharp edges with dynamic expressions, which is exactly how most teams use @image (passing a variable field value plus an options array).

Technical risk: Low-to-moderate.

• Dependency risk: ACF Pro licensing and version drift; several directives are non-functional without it.
• Bus factor: Historically near-single-maintainer. The new contributor is a positive indicator but does not change the underlying concentration.
• Correctness risk: Directive argument parsing is string-based; this release demonstrates that edge cases surface only in production template patterns. Escaping/output semantics for directives that emit raw markup (@shortcode, @svg, @image) should be reviewed once and codified.
• No formal support contract or LTS; governance is community GitHub issues.

Key questions for the team:

1. Which directives do we actually use, and which depend on ACF Pro vs. core WordPress?
2. What are our pinned Sage/Acorn, PHP, and WordPress versions, and do they satisfy the package's composer.json constraints?
3. Do we rely on @image with variable or empty-string options anywhere (i.e., are we in the blast radius of this fix)?
4. Who owns the ACF Pro license renewal, and what happens to rendering if it lapses?
5. Do we have visual regression coverage for image/responsive markup, or is QA manual?

Integration Approach

Stack fit: Appropriate only for Sage 10/11 themes using Acorn and Blade. Teams on classic PHP-template Sage 9, Timber/Twig, or standalone Laravel should not adopt it — the directives assume WordPress globals and ACF are loaded. For the target stack it is a strong fit: it reduces template noise and standardizes how field and query data reach the view.

Migration path: Incremental and reversible, which is the main appeal for a TPM. Replace raw get_field(), wp_get_attachment_image(), and new WP_Query blocks in Blade templates with directives file by file; keep raw calls where semantics are unusual. Pin ^2.0 in composer.json and commit the lockfile. v2.0.7 requires no code changes on our side — a routine composer update log1x/sage-directives is sufficient.

Compatibility: Confirm exact composer.json constraints (PHP, illuminate/support, Acorn) against our runtime before bumping. Note that the @image fix changes rendered output for previously-malformed argument cases — the change is a correction, but it is still a markup diff on affected templates. Clear compiled Blade views after deploy so cached templates pick up the new directive behavior.

Sequencing:

1. Verify composer constraints and ACF Pro availability in the target environment.
2. Upgrade in local/dev; grep templates for @image usages passing variables, empty strings, or function calls — those are the ones whose output may shift.
3. Stage deploy with a visual/markup diff on image-bearing pages (srcset, sizes, loading attributes, alt text).
4. Production release during a low-traffic window; clear Blade cache as part of the deploy step.
5. Retrofit remaining raw calls to directives opportunistically, not as a release-coupled task.

Operational Impact

Maintenance: Very low ongoing cost. Small code surface, infrequent releases, patch-level churn. The real maintenance burden is external: ACF Pro renewals and Sage/Acorn major upgrades, which will eventually force a directive-compatibility check. Keep the package in the lockfile and treat upgrades as routine patch bumps unless the changelog shows a minor/major.

Support: Community-only — GitHub issues and PRs, no SLA, no vendor. Assign an internal owner (typically the theme lead) who watches releases and can triage rendering regressions. Given the low release cadence, a quarterly review is adequate.

Scaling: Effectively zero runtime overhead beyond the underlying WordPress calls the directives wrap; directives compile into cached Blade views, so per-request cost is the same as hand-written PHP. Scales with the theme, not with traffic. No new caching, storage, or observability requirements.

Failure modes to plan for:

• Missing ACF Pro / plugin disabled: fatal undefined-function errors in templates, taking down page render. Guard critical templates or fail loudly at boot rather than mid-render.
• Directive argument parsing regressions: the class of bug fixed here. Mitigate with markup assertions on image-bearing templates.
• CLI or non-HTTP contexts: directives that assume a fully bootstrapped WordPress may behave unexpectedly in cron/WP-CLI rendering paths.
• Unescaped output: directives emitting raw markup are an injection surface if fed user-controlled content; enforce that field values are editor-owned, not visitor-supplied.
• Upgrade-adjacent cache staleness: stale compiled views masking the new behavior and causing confusing staging/production divergence.

Ramp-up: Low. A developer familiar with Blade and WordPress needs roughly half a day to be productive and a few days to be fluent across the directive catalog. Produce a short internal cheat sheet of the directives we sanction, the ones we forbid, and the escaping expectations — this is the highest-leverage documentation investment and prevents drift back to raw function calls.

Recommendation: Adopt and keep current on 2.x, including v2.0.7. The release is a low-risk correctness fix worth taking, with the only action item being a visual regression check on templates using @image with dynamic options.