Laravel Liquid Laravel Package

Getting Started

keepsuit/laravel-liquid brings the Shopify Liquid templating language to Laravel, so users can edit templates (emails, notification bodies, merchant-customisable pages) without touching PHP. As of v0.7.0-beta.1 it is a much better day-to-day tool: templates compile to PHP artifacts, cache warming is a single Artisan command, and streaming is available for large renders.

Minimal setup:

composer require keepsuit/laravel-liquid

Version constraints matter in this release: you need keepsuit/liquid ^0.13 and illuminate/contracts ^11.28. In practice that means Laravel 11.28+; Laravel 10 and older are out. If you are pinning, pin 0.7.0-beta.1 explicitly and accept minimum-stability: beta (or "keepsuit/laravel-liquid": "0.7.0-beta.1" with a beta allow-list) until it goes stable.

Then:

1. Publish the package config (php artisan vendor:publish --tag=liquid-config; check the package's publish tags) — this is where custom tags, filters and cache settings live.
2. Drop a .liquid file into resources/views and render it exactly like a Blade view:

return view('emails.receipt.liquid', ['order' => $order]);

3. Warm the cache before you ship: php artisan liquid:cache (it also participates in php artisan optimize).

Where to look first: the published config file (extension/handlers, filters, custom tags), then the compiled-artifact directory. Confirm that directory is writable in every environment, including your container build and deploy user.

The first use case to reach for: a template that non-developers need to change. Render it through view() so it sits alongside your existing view code, then add liquid:cache to your deploy pipeline.

Implementation Patterns

Two entry points, one cache. view('foo.liquid', $data) and the Liquid facade compile to the same PHP artifacts, so a template warmed once is warm for both. Use view() in controllers and Liquid::render(...) for programmatic or string-based templates, and don't worry about double-compiling.

Stream large renders. Liquid::stream('reports.monthly.liquid', $data) returns a streamed response rather than building the whole string in memory. Use it for long reports, exports, and large lists; keep view() for ordinary pages and emails where the response is small and you want normal response middleware to see the final body.

Warm the cache in deploy, not on first request. Add php artisan liquid:cache to your CI/CD step or rely on php artisan optimize in your deploy script. The payoff is bigger than it looks: because parse errors now surface at compile time, warming in CI turns broken templates into a failed build instead of a 500 on the first customer request.

Compile-time tags for personalisation. auth, guest and env are compiled. Use {% if auth %}/{% if guest %} to branch a template for signed-in versus anonymous users without two copies, and {% if env == 'production' %} for environment-specific inclusions. Keep these decisions coarse-grained; the compiled form means the result is baked into the artifact.

Custom tags and filters belong in config/providers. Register your domain filters (currency formatting, date formatting, markdown) centrally rather than duplicating formatting in templates. Keep filters pure and cheap — they run per render, and a filter that hits the database inside a loop will dominate your response time.

Testing. Assert on rendered output as you would for Blade. Snapshot tests are the cheapest way to catch the output changes below, but regenerate them deliberately after the upgrade rather than blindly accepting diffs.

Gotchas and Tips

The upgrade is not drop-in if you are on older Laravel. Dropping keepsuit/liquid 0.7–0.12 and requiring illuminate/contracts ^11.28 means a Laravel 10 application cannot take this release at all. Plan the Laravel upgrade first.

Number formatting changed. Integral floats now keep their .0 ({{ 3.0 }} renders 3.0), and math filters use decimal arithmetic. Any template, email or invoice that previously rendered 3 now renders 3.0. Audit templates and tests that print money, quantities or percentages; use round/floor/ceil or a dedicated formatting filter where you want an integer.

Templates are stricter at parse time. Incomplete if/elsif/unless conditions, empty tags, duplicate for/else sections and missing filter arguments throw SyntaxException when parsed instead of silently misrendering. This is a good change, but it means a template that "worked" before may now fail — run php artisan liquid:cache in CI so you find out at build time.

Compiled artifacts mean compile-time assumptions. Because tags are compiled to PHP, changing an environment variable read by {% if env %} will not take effect until the artifact is recompiled. Rebuild the cache whenever config or .env values feed into templates, not just when template files change.

Treat env as a footgun for user-editable templates. If merchants or admins can edit Liquid, the env tag exposes configuration values in template output. Gate template editing to trusted users, or avoid env entirely in user-facing templates.

Stale output is almost always a cache problem. If a template change isn't reflected, clear and rewarm (liquid:cache after deploying the new files) rather than hunting for a rendering bug. Check that the artifact directory is writable — permission failures in containerised deploys are the usual culprit.

Streaming has middleware limits. Response middleware that rewrites the body (compression, some response transformers) interacts poorly with streamed output. If a streamed view behaves differently from the same view rendered with view(), look at the middleware stack first.

Debugging. Read the SyntaxException message — it is specific about which construct failed. When a render surprises you, inspect the compiled PHP artifact; it is the fastest way to see how a tag or filter was actually interpreted.

Beta caution. This is a beta with breaking changes against 0.6.x. Pin the exact version, keep it out of the critical path until stable if you can, and re-read the keepsuit/liquid 0.13 changelog for output changes this package inherits but doesn't enumerate.