Fluid Laravel Package

Product Decisions This Supports

• Templating engine selection for PHP services. Fluid is a standalone, escaping-by-default PHP rendering engine with typed ViewHelper arguments. It is a real alternative to Blade/Twig when rendering is content-shaped (CMS-adjacent pages, marketing surfaces, localized content) rather than application-UI-shaped.
• Build vs. buy for a component/design system. The Annotations API, ViewHelper metadata, and component-listing API (v4.6/v5.2) let us generate a component catalogue from the templates themselves. That removes bespoke tooling work from the roadmap — a build-cost decision, not a feature decision.
• Where templating runs. Because the engine is standalone, the same templates can render in-app (transactional email, invoices, PDFs, notifications) and in the CMS. Choose this and we avoid a second, divergent template dialect owned by another team.
• Multi-tenant and white-label theming. The v5 template resolution fallback chain (*.fluid.html → *.html → bare name, with path-ordering preserved) supports per-tenant, per-package overrides without forking templates. This directly enables a packaging story: ship defaults, let customers override.
• Template ownership model. The CLI template analyzer, template-location-aware exceptions, and preserved line numbers make templates CI-checkable like code. That supports the governance call: templates reviewed in PRs by engineering vs. editable by content editors in a live system.
• Security posture / questionnaire answers. Escape-by-default with a single explicit UnsafeHTML opt-in interface gives an auditable bypass story — cheaper to defend in security review than "we escape in the controller."
• Roadmap timing. v5 is a deliberate modernization with breaking changes pre-announced during v4 (strict argument validation, file resolution/extension, deprecated AbstractTemplateView shortcuts). A v4→v5 upgrade is a plannable work item, not a surprise; the active v2.14 maintenance line also signals that older integrations aren't abandoned mid-flight.

When to Consider This Package

Consider it when:

• The stack is PHP and you want a template layer other than the framework default — particularly if TYPO3 interoperability is on the roadmap or the team already speaks Fluid.
• You want templates to fail loudly at the boundary: StrictArgumentProcessor enforces ViewHelper types (including union types, iterable, countable, callable), which retires a lot of hand-written validation code.
• You're standing up a component catalogue and want metadata plus listing APIs and an analysis CLI instead of custom tooling.
• You need deterministic template override/fallback behavior for white-labeling, package-provided defaults, or theme layering.
• Legal is comfortable with LGPL-3.0 as a dynamically consumed Composer dependency (standard for PHP libraries; escalate if you redistribute or statically embed).

Look elsewhere when:

• The team is Laravel-native. Blade is already present, better documented, and adds zero surface area. Twig is the stronger pick if you want a widely adopted, framework-agnostic engine.
• Ecosystem depth matters: 170 stars and effectively no independent dependents means the standalone community is thin — most real usage flows through TYPO3 itself. Expect no commercial support with SLAs.
• Documentation self-sufficiency is a requirement. Standalone docs repeatedly cross-reference the TYPO3 ViewHelper reference; budget for that reading curve.
• You cannot absorb major-version cadence. v4 and v5 arrived in succession with intentional breaking changes. Pin majors and schedule upgrades as owned work.
• You need client-side templating or JS parity — different problem entirely.

How to Pitch It (Stakeholders)

Executives. Fluid is a mature, actively released PHP templating engine with a security-conscious default (auto-escaping) and a maintenance trajectory that signals investment — v5 modernization plus continued v2/v4 maintenance lines. The strategic value isn't "a template engine"; it's that it lets us ship a governed component system with typed, validated, self-documenting templates and CI-checkable analysis, at low licensing cost under LGPL-3.0. The risk is ecosystem size: standalone adoption is small and documentation leans on TYPO3 material, so this should be a deliberate, contained choice with a named owner and pinned versions — not a platform-wide mandate. Recommend a scoped pilot with a clear success metric (time-to-new-component, template defect rate in CI) before committing.

Engineering. The case is trust in the template boundary: StrictArgumentProcessor makes declared ViewHelper types actually enforced, errors point at the offending template and line, and the Annotations + component-listing APIs plus the CLI analyzer drop straight into CI. Template resolution and override ordering are explicit and stable, so tenants and packages can override without forks, and escaping is on by default with UnsafeHTML as the one audited bypass. The costs are honest: a hard v4→v5 migration with pre-announced breaking changes (strict argument validation, .fluid.* extension and fallback resolution, deprecated AbstractTemplateView shortcuts), a small maintainer group, and docs that defer to TYPO3. Mitigate by pinning to a major, keeping our ViewHelper surface small and internal, adding template analysis to CI, and avoiding unmaintained third-party ViewHelper packs.