Flashy Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mercuryseries/flashy
   

   Publish the config (optional):

   php artisan vendor:publish --provider="MercurySeries\Flashy\FlashyServiceProvider" --tag="config"
   

2. Basic Usage Trigger a flash message in a controller:

   use MercurySeries\Flashy\Flashy;
   
   public function store(Request $request)
   {
       $request->validate([...]);
   
       // Success flash
       Flashy::success('Record saved successfully!');
   
       return redirect()->route('dashboard');
   }
   

3. Display in Blade Add this to your layout (e.g., resources/views/layouts/app.blade.php):

   @include('flashy::message')
   

First Use Case

• Form Submission Feedback: Use Flashy::error() for validation failures or Flashy::warning() for non-critical issues.
• Post-Action Redirects: Replace Session::flash() with Flashy::info() for user confirmation.

Implementation Patterns

Common Workflows

1. Conditional Flashing

   if ($user->save()) {
       Flashy::success('Profile updated!');
   } else {
       Flashy::error('Failed to update profile.');
   }
   

2. Queueing Flashes Store flashes in a queue (e.g., after async processing):

   Flashy::queue('Processing complete!', 'info');
   

3. Customizing Messages Override default messages in config/flashy.php:

   'success' => [
       'title' => 'Success!',
       'message' => 'Your action was completed.',
   ],
   

4. Integration with Requests Attach flashes to incoming requests (e.g., for API-like responses):

   $request->flashy()->success('Data fetched');
   

5. Blade Directives Create reusable directives for common flashes:

   Blade::directive('flash', function ($expression) {
       return "<?php echo MercurySeries\Flashy\Facades\Flashy::{$expression}(); ?>";
   });
   

   Usage:

   @flash('success', ['message' => 'Custom message'])
   

Advanced Patterns

• Flashy Middleware: Create middleware to auto-flash based on HTTP status:

  public function handle($request, Closure $next)
  {
      $response = $next($request);
      if ($response->getStatusCode() === 404) {
          Flashy::error('Page not found.');
      }
      return $response;
  }
  

• Flashy Events: Dispatch events for flash management:

  event(new FlashMessage('Login failed', 'error'));
  

• Localization: Extend translations via resources/lang/{locale}/flashy.php:

  'error' => [
      'title' => 'Error',
      'message' => 'Something went wrong.',
  ],
  

Gotchas and Tips

Pitfalls

1. Session Dependency

   • Flashes rely on the session. Ensure SESSION_DRIVER is configured (e.g., file, database, or redis).
   • Fix: Add to .env:

     SESSION_DRIVER=file
     

2. Double Flashing

   • Redirects with with() or withInput() may conflict with Flashy.
   • Fix: Clear flashes before redirecting:

     Flashy::clear();
     return redirect()->withInput()->route('dashboard');
     

3. Queue Delays

   • Queued flashes may not appear immediately if the queue is backed (e.g., database).
   • Fix: Use Flashy::now() to bypass the queue:

     Flashy::now()->success('Immediate message');
     

4. Blade Caching

   • Cached views may not reflect new flashes.
   • Fix: Clear Blade cache:

     php artisan view:clear
     

Debugging Tips

• Check Session Data: Dump the session to verify flashes:

  dd(session()->all());
  

• Inspect Config: Verify config/flashy.php overrides:

  dd(config('flashy'));
  

• Log Flashes: Add a listener to log flashes:

  Flashy::listen(function ($message) {
      Log::info('Flash triggered:', ['message' => $message]);
  });
  

Extension Points

1. Custom Flash Types Extend the Flashy facade to add methods:

   // app/Providers/AppServiceProvider.php
   Flashy::extend('custom', function ($message) {
       return Flashy::add('custom', $message, 'custom-class');
   });
   

   Usage:

   Flashy::custom('This is a custom flash!');
   

2. Override Blade View Publish and modify the Blade template:

   php artisan vendor:publish --tag="flashy-views"
   

   Edit resources/views/vendor/flashy/message.blade.php to customize styling/behavior.

3. API Responses Use Flashy with API responses (e.g., Laravel Sanctum):

   return response()->json(['data' => $data], 200)
       ->withHeaders(['X-Flash' => Flashy::getJson()]);
   

   Client-side: Parse X-Flash in JavaScript.

4. Testing Mock flashes in tests:

   $this->actingAs($user)
        ->post('/submit', $data)
        ->assertSessionHas('flashy', ['type' => 'success', 'message' => 'Saved!']);