Laravel Liquid Laravel Package

Technical Evaluation

Architecture fit

• Liquid is a second view engine sitting alongside Blade, resolving through Laravel's view finder plus a Liquid facade. The v0.7 line moves it onto Blade's model: templates compile to PHP artifacts that are opcache-able and warmable via php artisan optimize. That is the single most architecturally significant change — it converts Liquid from an interpreted sidecar into a first-class, cacheable view layer.
• Compilation is now shared between view() and the Liquid facade, which removes a prior inconsistency where the two entry points could behave differently under caching. Fewer divergent code paths is a governance win, not just a perf win.
• The auth, guest and env tags now compiling means conditional/gated rendering gets the same treatment. Worth confirming these compile to something equivalent semantically — environment-dependent compiled artifacts are a classic source of "works in staging, wrong in prod" bugs if the compiled output is cached across environments.
• Countervailing concern: two template languages, two caching strategies, two debugging mental models. That's a maintainability tax paid by every engineer who touches a view.

Integration feasibility

• This is a coupled upgrade, not a drop-in. illuminate/contracts ^11.28 sets a hard floor on Laravel 11.28, and keepsuit/liquid ^0.13 drops 0.7–0.12 of the core engine. Anyone on Laravel 10, or on an early 11.x, is blocked behind a framework upgrade first.
• It is a beta (0.7.0-beta.1) built on a 0.x core library. Neither carries a semver stability guarantee on the underlying engine. That is acceptable for a spike, questionable for a production dependency of record.

Technical risk

• Silent output drift (highest severity, lowest visibility). Integral floats retain .0 ({{ 3.0 }} → 3.0) and math filters switch to decimal arithmetic. Anything rendering money, quantities, percentages or metrics to a downstream consumer — JS, CSV export, API payload, transactional email — can change format with no error raised. Decimal arithmetic may also change rounding on edge values.
• Parse-time strictness (high severity, high visibility). Incomplete if/elsif/unless conditions, empty tags, duplicate for/else sections and missing filter arguments now throw SyntaxException at parse time. These are latent template bugs that were previously tolerated; they become hard failures, and likely only on rarely-exercised branches — i.e. in production, on the least-tested page.
• Blast-radius shift at deploy time. Because liquid:cache is wired into php artisan optimize, a single malformed template can now fail the optimize step and therefore the release, rather than failing one request. Fail-fast is the right posture, but it means one tenant's bad template can block everyone's deploy.
• Beta status. Combined with the above, the risk profile is "high change density, low compatibility commitment."

Key questions

1. Are we on Laravel ≥ 11.28 everywhere, and does raising the illuminate/* floor force other package upgrades?
2. Do we have a complete inventory of Liquid templates in the estate, including tenant-authored/user-authored ones we don't control?
3. Which templates render floats or use math filters in user-facing or machine-consumed output?
4. What is the compiled-artifact invalidation model — hash/mtime-based, or does it require an explicit rebuild after a template edit?
5. Is our filesystem writable and persistent enough for a compiled cache (read-only root FS, ephemeral containers, multi-tenant overrides)?
6. Do we need compilation or stream() now, or is the honest answer "stay on 0.6.3 until 0.7.0 GA"?
7. What is the support/security posture if the beta stalls or the core library makes another breaking 0.x jump?

Integration Approach

Stack fit

• Requires Laravel 11.28+ / keepsuit/liquid ^0.13. Natural placement is Blade for application chrome and layout, Liquid strictly for user- or tenant-authored content. That containment keeps the stricter parser and the output changes off our own critical pages and limits who is exposed to them.

Migration path

• Treat this as two independent moves and do not bundle them: (a) framework floor to Laravel ≥ 11.28 and core engine to ^0.13; (b) behavioural validation of template output. Bundling them makes any regression ambiguous to diagnose.
• Adopt the beta only if we specifically want compiled views or stream(). Otherwise pin 0.6.3, track 0.7.0 GA, and take the fixes then — we lose nothing but time, and we avoid carrying a beta plus a 0.x engine bump simultaneously.

Compatibility

• Audit composer.json for any direct or transitive pins on illuminate/contracts and sibling illuminate/* packages; a 11.28 floor can ripple and drag other upgrades with it.
• Confirm nothing pins the now-dropped core range 0.7–0.12 transitively, and that no internal package wraps Liquid APIs that changed.
• Verify compiled-artifact storage against our deploy model before committing: read-only root filesystems, per-container caches and shared-nothing autoscaling all change the answer.

Sequencing

1. Template inventory: enumerate all Liquid templates, tags and filters in use; flag floats, math filters and any if/elsif/unless without a complete condition.
2. CI parse gate: a script that parses every template against 0.13 and fails the build on SyntaxException. This converts production 500s into build failures — do this before anything else.
3. Golden-file output diff: render a representative template set on both versions and diff the output, with explicit attention to numerics and rounding. This is the only defence against the silent drift class of bug.
4. Framework upgrade to ≥ 11.28 on a branch, isolated from step 2–3 results.
5. Enable compiled views and liquid:cache in staging; measure cold start vs. 0.6.3; confirm invalidation behaves on template edit.
6. Pilot one tenant or one low-risk surface.
7. Production rollout with an explicit rollback to 0.6.3 and a flag to disable compilation if cache behaviour surprises us.

Operational Impact

Maintenance

• New lifecycle to own: liquid:cache now runs as part of php artisan optimize, so every deploy pipeline, image build and any scheduled optimize inherits it. Someone must own that step and know what it does on failure.
• The core question is invalidation. If compiled artifacts are keyed on template hash/mtime, edits self-heal. If not, tenant template edits silently serve stale output until a rebuild — an insidious, hard-to-reproduce support ticket. Resolve this before GA, not after.
• Upgrade reviews now span two changelogs: the package punts output and parser detail to the keepsuit/liquid changelog. Budget for that permanently, and pin exact versions rather than using ranges.

Support

• Beta package on a 0.x core is a low-commitment support surface: no deprecation windows, no LTS. Assume we may need to patch or vendor a fix, and confirm someone on the team can read the compiler.
• Expect a short tail of "this page used to render and now 500s" tickets immediately post-rollout unless the CI parse gate is in place first.

Scaling

• Compilation is the real win: parse cost leaves the request path, artifacts sit in opcache, and stream() reduces peak memory and improves TTFB on large renders. Both help linearly with traffic, unlike the interpreted path.
• Cost moves to warmup. Every new container needs a warm compiled cache — run optimize in the image build, not at container start, or autoscaling events will produce latency spikes. More containers and more tenants mean proportionally more cache to warm and more templates to invalidate.
• stream() is a targeted tool, not a default: use it for large, low-interactivity documents only.

Failure modes

1. Render-time SyntaxException on a template that previously degraded gracefully — 500 on a page that "worked." Mitigate with the CI parse gate; do not rely on manual review.
2. Silent numeric formatting drift from float .0 retention and decimal math — no error, wrong display or wrong downstream parse. Worst failure class; mitigate only with golden-file diffing.
3. Stale compiled artifacts after template edits, if invalidation is not edit-aware.
4. Deploy-wide failure from one bad template, since optimize runs at release time. Better than a per-request failure, but it changes who owns the blast radius — one tenant's content can block a release.
5. Mid-stream errors — once stream() has flushed headers we cannot switch to an error page or adjust status. Restrict streamed views to the simplest, best-tested templates.
6. Environment-divergent compiled env tags if artifacts are shared across environments.

Ramp-up

• Two distinct skill gaps: Liquid literacy (not Blade — different tag semantics, filter behaviour, loop scoping, whitespace control) and the new compiled-view cache model. Both need a documented internal guide, not tribal knowledge.
• Recommend a short timeboxed spike: upgrade on a branch, run the parse gate and golden-file diff against the real template corpus, measure cold start in staging. That spike produces the actual go/no-go for the beta and most of the guide, and it is cheap relative to discovering failure mode 1 or 2 in production.