Blade Laravel Package

Getting Started

The 13.4.0 release ships with only a compare link (13.3.13...13.4.0) and no described changes, so treat the upgrade as a low-signal patch-level bump: assume nothing breaking, but verify the diff before rolling it across a fleet of apps.

composer require larastash/blade
php artisan vendor:publish --tag=blade-config   # if the package registers publishable config

Look first at:

1. The service provider — it tells you what's auto-registered (Blade directives, component namespaces, view paths). Everything else in the package is downstream of that registration.
2. config/blade.php (or equivalent) — feature flags, component path overrides, and any caching toggles usually live here.
3. The component/directive directory — this is the public surface you'll actually call from templates.

First use case: take one repetitive chunk of markup in an existing view — a card, a badge, a form field wrapper — and convert it into a package-provided component or directive. Confirm it renders in both APP_ENV=local and with php artisan view:cache run, because a package that works uncached and breaks cached is the single most common Blade-tooling failure.

Because the release notes are empty, baseline your current behaviour before upgrading:

php artisan view:clear
php artisan about        # capture versions
# run the test suite, ideally with view compilation assertions

If you can't read the diff, pin to 13.4.0 explicitly rather than using a ^13.4 caret while you validate—this gives you a one-line revert.

Implementation Patterns

Wrap, don't replace. Package-level Blade helpers age badly when they're used as the primary abstraction. Use them for leaf presentation (icons, badges, layout primitives) and keep domain-aware markup in your own resources/views/components. That way a future 14.x rewrite touches a small blast radius.

Directive vs. component. Prefer class-based components (<x-vendor::thing />) over custom directives for anything with attributes or slots—directives are stringly-typed and don't compose. Reserve directives for control-flow-style constructs (@feature, @cache, @once-like behaviour) where a tag would be awkward inside an attribute or a loop.

Component namespace registration. If the package exposes components, register the namespace once in a provider rather than prefixing every call site:

Blade::componentNamespace('Larastash\\Blade\\Components', 'stash');
// <x-stash::card />

This keeps templates readable and makes a future package swap a single-line change.

Slot hygiene. When composing package components inside your own, pass slots through explicitly rather than relying on $slot magic:

<x-stash::panel {{ $attributes->except('title') }}>
    <x-slot:title>{{ $title }}</x-slot:title>
    {{ $slot }}
</x-stash::panel>

Attribute merging. Favour $attributes->class([...])->merge([...]) over manual string concatenation. It's the difference between Tailwind classes that merge cleanly and ones that silently duplicate.

Integration with Livewire / Inertia. If your app uses Livewire, verify package components survive a re-render—components that capture request state in the constructor will break on subsequent renders. If you use Inertia, most Blade-only helpers are irrelevant; keep them out of that codebase rather than half-adopting them.

Testing. Add a small Blade render test per component you adopt:

it('renders the stash card', function () {
    $this->blade('<x-stash::card title="Hi">Body</x-stash::card>')
        ->assertSee('Hi')
        ->assertSee('Body');
});

This is cheap insurance and catches the "works locally, breaks in CI" class of view-cache bugs.

Gotchas and Tips

The empty changelog is the gotcha. A version bump with no notes is not evidence of no change—it's evidence of no documented change. Before upgrading production apps, read the compare diff directly. If you're on 13.3.x and stable, there's rarely urgency to move on a patch with no stated fixes.

View cache is the #1 debug lever. Any weirdness—components not found, stale markup, directives not registering—start with:

php artisan view:clear && php artisan cache:clear

In production, remember view:cache is a deploy step. If your deploy pipeline doesn't recompile views, you'll ship new package code against old compiled templates and get confusing partial failures.

Namespace collisions. Custom directives are global. If two packages register @cache or @once, whichever boots last wins—silently. Grep your composer.json for other Blade-adjacent packages before adopting new directives, and consider a vendor prefix in your own code.

Escaping and Htmlable. Package components that return HTML from a class must implement Htmlable or be rendered via {{ }} on a safe value; otherwise you'll double-escape or reach for {!! !!} and create an XSS surface. Audit any component before accepting user-supplied slot content.

Config caching. If the package registers anything config-driven at boot, php artisan config:cache can freeze values at deploy time. Test the full config:cache && route:cache && view:cache sequence locally before trusting a green staging deploy.

Version pinning as a strategy. Given the sparse release notes across 13.x, pin to exact versions in composer.json for this package and let Renovate/Dependabot open PRs you review against the diff. For a presentation-layer dependency, the cost of an unexpected rendering change outweighs the benefit of automatic minor bumps.

Escape hatch. If the package stops being maintained, the migration path is mechanical: copy the component classes into app/View/Components, keep the same tag names via namespace registration, and delete the dependency. Design your call sites so that this stays a one-afternoon job—that's the real mitigation for a package whose changelogs you can't rely on.