Sage Directives Laravel Package

Product Decisions This Supports

• Build vs. buy (theme templating): The package is a thin, MIT-licensed directive layer that replaces hand-rolled add_action/add_shortcode-style Blade directives and repeated get_field() echo blocks in WordPress themes. Adopting it converts weeks of bespoke glue code into a dependency — a straightforward buy.
• Feature: editor-controlled media. The headline fix in v2.0.7 (correctly resolving @image options when values are empty strings, variables, or function calls) directly affects templates where image sizing/attributes are driven by ACF fields or computed values rather than hardcoded strings. If your roadmap includes responsive image sets, art direction, or per-block image controls authored by editors, this fix is a prerequisite, not a nice-to-have.
• Roadmap risk / standardization: A 2.0.7 patch containing only a bug fix and a typo is a maturity signal — the 2.x API is stable and the maintainers are shipping surgical fixes rather than churn. That supports standardizing the package across all Sage themes in the portfolio and budgeting near-zero migration effort for minor bumps.
• Use cases to prioritize: ACF-heavy content models (flexible content, repeaters, option pages), component-driven Blade partials, and multi-theme agencies with a shared directive vocabulary.
• Dependency posture: Treat it as a low-velocity infrastructure dependency. Don't put it on the roadmap; put it in the starter theme template and forget it.

When to Consider This Package

Adopt when most of these hold:

• You are on a Roots/Sage stack (or any WordPress theme wired up with Blade via illuminate/view) — the package assumes Blade, not Laravel's HTTP stack.
• Advanced Custom Fields is in the stack and licensed/available; most directives (@field, @sub, @image, @repeater, @group, @options, @shortcode, @hasfield, etc.) are ACF and WordPress API wrappers.
• Templates are drifting toward PHP soup and you want declarative, reviewable markup that designers and front-end devs can read.
• You value a small, single-purpose dependency over a framework-sized page-builder plugin.

Look elsewhere when:

• The application is Laravel proper — you want Blade components, @props, and view composers, not WordPress shims.
• The theme is block-based / full-site-editing; core blocks and theme.json cover most of what these directives do, and ACF Blocks has its own rendering path.
• You need actively evolving features — this is a maintenance-mode utility; a patch-only release cadence means no roadmap to lean on.
• ACF is unavailable (licensing constraints) or content is modeled entirely through custom post meta without ACF.
• You require first-party vendor support or an SLA.

How to Pitch It (Stakeholders)

For executives: This is a small, free, MIT-licensed open-source utility that removes custom code from our WordPress theme builds. It is mature — the current release, v2.0.7, is a bug-fix-only patch that corrects how image options are resolved when values are dynamic or empty, plus a documentation typo. No new API, no deprecations, no breaking changes, no migration work. Net effect: lower maintenance surface, faster theme delivery, negligible supply-chain risk.

For engineering: Directives are declarative sugar over ACF and WordPress template functions, so the upgrade is a drop-in composer update — no code changes required. The @image fix is the one to validate: any template passing variables, function calls, or empty strings into @image options was previously producing incorrect output and will now behave as expected. Add a smoke test on image-heavy templates (hero, cards, galleries) and confirm output markup and srcset are unchanged where options were already literal strings. Pin to ^2.0 and let patch releases flow; review minor bumps for ACF/Sage compatibility.