Flasher Noty Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require php-flasher/flasher-noty
   

   Ensure php-flasher/flasher (≥2.5.1) is installed as a dependency.

2. Publish Config (Optional):

   php artisan vendor:publish --provider="PHPFlasher\Flasher\FlasherServiceProvider" --tag="flasher-config"
   

   Locate config at config/flasher.php under the noty section.

3. First Use Case:

   // In a controller or Blade view
   noty('User created successfully!', 'success');
   

   This renders a Noty toast at the default position with the success theme.

Where to Look First

• Config: config/flasher.php (Noty-specific settings like default_layout, theme).
• Helper Functions: Global noty() helper in app/helpers.php (auto-loaded via FlasherServiceProvider).
• Queue System: Flasher::queue() for managing notification order (e.g., during form submissions).

Implementation Patterns

Core Workflows

1. Basic Notifications

// Controller
public function store(Request $request) {
    $validated = $request->validate([...]);
    noty('Record saved.', 'success');
    return back();
}

• Blade Integration: Notifications auto-render in Blade via @flasher directive.

  @flasher
  

2. Customizing Appearance

noty('Warning: Low disk space.', 'warning', [
    'layout' => 'bottomRight',
    'theme' => 'metroui',
    'timeout' => 5000,
]);

• Dynamic Themes: Use config('flasher.noty.theme') to override globally.

3. Queue Management

// Order notifications (e.g., for multi-step forms)
Flasher::queue('error', 'Invalid data.', ['timeout' => 2000]);
Flasher::queue('success', 'Data processed.');
Flasher::flush(); // Render all queued notifications

4. Conditional Notifications

if ($user->save()) {
    noty('Profile updated.', 'success');
} else {
    noty('Update failed.', 'error', ['closeWith' => ['click']]);
}

Integration Tips

• API Responses: Use Flasher::json() for API feedback:

  return Flasher::json(['message' => 'Success'], 200, 'success');
  

• Event-Based Triggers: Bind to Laravel events:

  Event::listen(UserCreated::class, function ($event) {
      noty('New user registered: ' . $event->user->name, 'info');
  });
  

• JavaScript Hooks: Extend Noty via notyOptions in config:

  'notyOptions' => [
      'onShow' => 'function() { console.log("Notification shown!"); }',
  ],
  

Gotchas and Tips

Pitfalls

1. Queue Ordering:

   • Notifications in Flasher::queue() render in FIFO order. Use Flasher::flush() explicitly to control timing.
   • Fix: Call Flasher::flush() after all queued notifications are set.

2. Theme Conflicts:

   • Noty themes (e.g., metroui, bootstrap_v4) require their CSS/JS. Ensure assets are loaded:

     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/noty@3.2.0/dist/noty.min.css">
     <script src="https://cdn.jsdelivr.net/npm/noty@3.2.0/dist/noty.min.js"></script>
     

   • Tip: Use config('flasher.noty.theme') to standardize themes across the app.

3. Session Dependence:

   • Flash messages rely on the session. Ensure SESSION_DRIVER is configured (e.g., file, database).
   • Debug: Check session()->get('flasher') for stored messages.

4. JavaScript Errors:

   • If Noty fails to render, verify:
     • jQuery is loaded (Noty v3+ requires it).
     • No console errors (e.g., missing notyOptions keys).
   • Fix: Use notyOptions validation in config:

     'notyOptions' => [
         'timeout' => 3000, // Ensure valid keys
     ],
     

Debugging

1. Log Notifications: Add a middleware to log all noty() calls:

   public function handle($request, Closure $next) {
       if (app()->bound('flasher')) {
           \Log::debug('Flasher:', app('flasher')->getMessages());
       }
       return $next($request);
   }
   

2. Inspect Queued Messages:

   dd(Flasher::getQueuedMessages()); // Debug queue state
   

Extension Points

1. Custom Noty Types: Extend Noty’s types by registering a new helper:

   // app/Providers/AppServiceProvider.php
   public function boot() {
       Flasher::extend('custom', function ($message, $options = []) {
           return noty($message, 'custom-type', $options);
       });
   }
   

   Use via noty('Message', 'custom') or flasher('custom', 'Message').

2. Override Default Renderer: Replace Noty’s JavaScript renderer by publishing the view:

   php artisan vendor:publish --provider="PHPFlasher\FlasherNoty\FlasherNotyServiceProvider" --tag="views"
   

   Modify resources/views/vendor/flasher/noty.blade.php.

3. Queue Priorities: Implement priority-based queues:

   Flasher::queue('error', 'Critical error!', ['priority' => 1]);
   Flasher::queue('info', 'Info message.', ['priority' => 2]);
   

   Tip: Sort queued messages by priority before flushing.

Performance Tips

• Batch Notifications: Group related notifications (e.g., form validation errors) into a single queue flush.
• Lazy Loading: Defer Noty JS/CSS loading until a notification is triggered:

  @if(session()->has('flasher'))
      <script src="https://cdn.jsdelivr.net/npm/noty@3.2.0/dist/noty.min.js" defer></script>
  @endif
  

• Timeout Optimization: Use shorter timeouts (e.g., 2000ms) for non-critical messages to reduce UI clutter.