Laraflash Laravel Package

Getting Started

Laraflash is a small, single-purpose package for flashing temporary messages to the session and rendering them in views. It is not a framework — it is a thin convenience layer — so the fastest path is to read the source before wiring it in.

1. Install it:

   composer require binkap/laraflash
   

2. Check whether the service provider is auto-discovered. Open vendor/binkap/laraflash/composer.json and look at extra.laravel.providers and extra.laravel.aliases. If they are absent, register the provider and facade manually in config/app.php.

3. Look first at these files, in this order:

   • README.md — the only authoritative usage documentation.
   • src/*ServiceProvider.php — what is bound, whether config/views are publishable.
   • The facade or helper file — the actual public API surface (method names, message types).
   • config/laraflash.php (if present) — session key, view path, default types.
   • tests/ — the package's own tests are the best specification of behavior.

4. Publish assets only if the provider exposes them:

   php artisan vendor:publish --provider="Binkap\Laraflash\LaraflashServiceProvider"
   

5. First use case — flash after a form submission and render in your layout:

   // app/Http/Controllers/PostController.php
   public function store(StorePostRequest $request)
   {
       Post::create($request->validated());
   
       laraflash()->success('Post created.'); // confirm exact API in README
   
       return redirect()->route('posts.index');
   }
   

   {{-- resources/views/layouts/app.blade.php --}}
   @include('laraflash::messages') {{-- or the documented partial --}}
   

   Verify the redirect renders the message once, then disappears on the next request. That single loop confirms session wiring, provider registration, and view resolution all at once.

Implementation Patterns

Wrap the package behind your own helper. Given the package's size (18 stars, no dependents, last release April 2024), avoid scattering laraflash()->... calls across the codebase. Create app/Support/Flash.php with methods like success(), error(), warning() that delegate to the package. If you later swap to Laravel's native session()->flash() or a livewire-friendly alternative, you change one file.

namespace App\Support;

class Flash
{
    public static function success(string $message): void
    {
        laraflash()->success($message);
    }
}

Controller → redirect → layout. The canonical workflow is: mutate state, flash, redirect, render in the shared layout. Keep the render partial in your layout rather than per-view so you do not forget it on new pages.

Use it for API responses too, if the package supports arrays. If the facade exposes a toArray() or the messages are session-backed, you can read them in a middleware and merge into JSON responses. Otherwise, keep it server-rendered only and use a separate response envelope for APIs.

Centralize message text and translation. Pass keys, not literals, so messages stay translatable:

Flash::success(__('posts.created'));

Test with session assertions. Because flashes live in the session, you can assert without touching the package internals:

$response = $this->post('/posts', [...]);
$response->assertRedirect('/posts');
$response->assertSessionHas('laraflash'); // confirm the actual key

If the package ships its own assertion helpers, prefer those — but fall back to assertSessionHas against the documented session key.

Integration with Livewire/Inertia.

• Inertia: flashes must survive the redirect and be shared via HandleInertiaRequests::share(). Read the session key there and expose it as a prop; render toasts client-side.
• Livewire: session flashes do not survive component re-renders cleanly. Flash in the redirecting action and render on the destination page, not inside the component.

Layered views. Override the package's Blade partial by publishing views (if supported) into resources/views/vendor/laraflash/. This lets you style messages with your own Tailwind/Bootstrap components without forking.

Gotchas and Tips

• Low-adoption risk. No dependents and a single release in 2024 means limited real-world coverage. Pin the exact version in composer.json, and be prepared to fork. The package is small enough that reading all of src/ takes minutes — do it before depending on it.
• Do not double-flash. If you also use Laravel's native session()->flash('status', ...), you may render the same message twice or diverge on styling. Pick one path per message category.
• Session lifecycle. Flashes are consumed on the next request. A redirect chain (e.g., auth middleware bouncing) can swallow a message before the user sees it. If messages vanish, dump session()->all() after the redirect.
• Config caching. If the package reads a config file, run php artisan config:clear after edits — config:cache in production can mask changes and occasionally cause "class not found" if the provider registration is stale.
• Provider/alias registration. Non-auto-discovered packages fail silently as "class not found" or "method not found." Confirm extra.laravel in the vendor's composer.json first.
• Escaping. Flash messages often contain user input (e.g., "Welcome back, {{ name }}"). Use {{ }} in the partial, never {!! !!}, unless you consciously pass pre-sanitized HTML.
• Version constraints. Check the package's composer.json for supported Laravel/PHP ranges. On newer Laravel versions, watch for deprecations in facades or Str helpers. If constraints block you, a fork with a widened require is usually trivial.
• Extension points to look for: a custom renderer/transformer class, overridable view path, a configurable session key, and facade macros (via Facade::macro) for custom message types. If none exist, wrap rather than fork.
• Debugging checklist when a message does not render: (1) is the provider registered, (2) is the flash actually in the session after redirect, (3) is the partial included in the current layout, (4) is the correct session driver active (file/redis/database all behave the same for flashes, but array in tests will not persist), (5) is a view override shadowing the package's default with a broken path.
• Production hardening. Add a smoke test that posts to a form and asserts the flash key, so an upstream change or a Laravel upgrade that breaks the thin layer is caught in CI rather than by users.