edalzell/blade-directives
A handy collection of custom Laravel Blade directives that add convenient shortcuts for common template logic, conditionals, debugging, and more, helping you write cleaner, more readable views without extra PHP.
Install and confirm the version matrix first. The package is a small add-on that registers Blade directives backed by Statamic's tag/runtime APIs, so the only install step is:
composer require edalzell/blade-directives
There is normally nothing to publish — the service provider auto-registers and calls Blade::directive(...) for each directive. Before writing any markup, open two things:
Directives directory in vendor/edalzell/blade-directives/src — this is where each directive class lives and where you confirm exactly which Statamic tag each one wraps. Read this before assuming a directive behaves like the Antlers tag of the same name.Where it fits. Statamic already renders *.blade.php files from resources/views as templates, so plain Blade works out of the box. The gap this package fills is the Antlers-only surface area: collections, navs, Glide images, forms, Bard rendering, and the @antlers escape hatch. Reach for it when a project is Blade-first (Livewire, Alpine, a design system built on Blade components) but still needs to pull Statamic content.
First use case. Take an existing Antlers partial that loops a collection and port it:
@collection('news', ['limit' => 3, 'sort' => 'date:desc'])
<article>
<h2><a href="{{ $entry->url() }}">{{ $entry->title }}</a></h2>
{!! $entry->augmentedValue('teaser')->value() !!}
</article>
@endcollection
Run it against a single template file first (resources/views/news.blade.php), confirm the loop variable name ($entry here — verify in the README), then migrate outward. Do not attempt a big-bang conversion of an entire Antlers site.
Treat @antlers as the migration seam, not a permanent tool. Every Blade template you convert should keep one @antlers block for the awkward parts — complex conditionals, {{ if }} chains, custom tags the package does not wrap. This lets you convert incrementally and keeps the diff reviewable. Plan to retire these blocks as you learn the native directives; leaving @antlers sprinkled everywhere means you pay Antlers' parse cost inside a Blade render with none of the readability benefit.
Wrap directives in Blade components for anything reused. The raw directives have loose, array-based signatures that are easy to get wrong at a call site. Once a pattern is used twice, promote it:
{{-- resources/views/components/news-card-list.blade.php --}}
@props(['collection' => 'news', 'limit' => 3])
@collection($collection, ['limit' => $limit, 'sort' => 'date:desc'])
<x-news-card :entry="$entry" />
@endcollection
Now the directive is a one-line detail inside a component, and your views read like normal Blade.
Pass data down explicitly. Directives that render sub-views or tag output do not reliably inherit every outer variable — especially inside @foreach/@collection nesting. Use @include('partial', ['entry' => $entry]) rather than assuming $entry leaks into an included file. When a value looks empty for no reason, this is almost always the cause.
Use @glide/image directives at the component boundary. Statamic's Glide is the main reason a Blade-first site still needs this package. Put image presets behind a component prop (size="card") that maps to a Glide argument array, so template authors never type Glide params inline.
Interop with Livewire/Alpine. Alpine's @click and x-on: do not conflict with these directives, but be aware that directives are compile-time substitutions — they run once when the view is compiled, not on every Livewire re-render of a public property. If a Livewire component needs fresh Statamic data, pull it in the component's mount()/render() via the Statamic API and pass it as a property; do not rely on a directive inside the Livewire view to re-query.
Rendering from routes and mail. A useful pattern outside the CMS: register a normal Laravel route or a Mailable whose view uses @collection/@nav. This lets you reuse Statamic content in transactional email and JSON-adjacent endpoints without writing Antlers strings in PHP.
Directive name collisions. @svg and @include-adjacent names are the classic conflict zone — other Blade helper packages (blade-svg, blade-icons, blade-ui-kit) register the same identifiers. Laravel keeps the last registered directive, so load order decides the winner and the failure mode is silent (wrong SVG, or an exception deep in the tag runtime). Run php artisan tinker and check array_keys(Blade::getCustomDirectives()) to see what actually won, and grep composer.json for competing packages.
No escaping safety net. A directive emits raw PHP/HTML at compile time; it ignores {{ }} vs {!! !!} conventions entirely. That means @antlers($userInput) is template injection if the string is user-supplied. Never feed request data, form submissions, or imported CMS fields into @antlers — pass them into the Blade context as values instead.
N+1 inside @collection. Each directive invocation typically resolves through Statamic's tag layer, which hits the repository. Putting a directive inside a @foreach over 50 items will produce 50 lookups. Hoist the loop to the directive (@collection(... ) once, loop inside), or wrap with @cache. Enable query logging (DB::listen) for one page load and count queries before you trust a page's performance.
Static caching and Blade. Statamic's static cache stores the final response, which is fine — but if you use @cache or a "last updated" element in a Blade template, make sure the cache invalidation story is deliberate. Blade's compiled-view cache (storage/framework/views) is not the same thing; clearing it with view:clear will not fix stale Statamic data, and clearing Statamic's cache will not recompile Blade. Debug both when output looks frozen.
Version pinning is the real risk here. This is a single-maintainer package with very low adoption (zero dependents at time of writing) and a non-trivial compatibility surface across Statamic majors and Laravel's Blade compiler. Pin it to an exact minor in composer.json, read the changelog before every composer update, and have an exit plan. The exit plan is cheap: each directive is a thin wrapper. Copy the handful you actually use into app/Support/Blade/ and register them yourself in AppServiceProvider::boot() with Blade::directive(). Budget an afternoon; doing this proactively for the two or three directives you depend on most is often cheaper than owning the dependency.
Debugging a directive that "does nothing". Order of checks: (1) is the compiled view stale — php artisan view:clear; (2) does the directive name match the README exactly, including any @foo:bar colon syntax; (3) is the underlying Statamic tag returning empty because of a missing .current/locale/site context (very common in multi-site and in mailables rendered outside a request); (4) dd() the argument array at the top of the vendor directive class to see what actually arrived. Editing vendor/ temporarily is the fastest path to comprehension with a package this small — just remember to revert or fork.
How can I help you explore Laravel packages today?