Alerts Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require prologue/alerts
   

   Publish the config (optional but recommended for customization):

   php artisan vendor:publish --provider="Prologue\Alerts\AlertsServiceProvider" --tag="config"
   

2. Basic Usage Trigger an alert in a controller or middleware:

   use Prologue\Alerts\AlertManager;
   
   public function showAlert()
   {
       Alert::success('Operation completed!')->persist();
       // or
       Alert::error('Something went wrong.')->persist();
   }
   

3. View Integration Add the alert blade directive to your master layout (e.g., resources/views/layouts/app.blade.php):

   @alerts
   

First Use Case

Display a success message after a user registers:

// In your registration controller
public function register(Request $request)
{
    // ... registration logic
    Alert::success('Account created! You can now log in.')->persist();
    return redirect()->route('login');
}

Implementation Patterns

Common Workflows

1. Conditional Alerts Use alerts dynamically based on business logic:

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

2. Alert Persistence

   • Temporary Alerts: Defaults to session-based (cleared on redirect).
   • Persistent Alerts: Use ->persist() to retain across redirects.
   • Flash Alerts: Use ->flash() to clear after the next request.

3. Alert Types Leverage built-in types (success, error, warning, info) or create custom ones:

   Alert::custom('custom-type', 'Custom message')->persist();
   

4. Alert Dismissal Add a dismiss button to alerts in your view:

   @alerts(['dismissible' => true])
   

Integration Tips

• Middleware: Flash alerts before redirecting:

  public function store(Request $request)
  {
      $request->session()->flash('alert-success', 'Item saved!');
      return redirect()->back();
  }
  

  (Note: The package also supports Laravel’s native flash data.)

• API Responses: Use alerts for API responses (e.g., with Laravel Sanctum):

  return response()->json(['message' => Alert::success('Action completed.')->getMessage()]);
  

• Custom Views: Override default alert templates by publishing views:

  php artisan vendor:publish --provider="Prologue\Alerts\AlertsServiceProvider" --tag="views"
  

• Queue Alerts: For delayed alerts (e.g., email confirmation):

  Alert::success('Check your email for confirmation.')->delay(10); // Delay in seconds
  

Gotchas and Tips

Pitfalls

1. Session Dependence

   • Alerts rely on sessions. Ensure SESSION_DRIVER is configured in .env (e.g., SESSION_DRIVER=file for local testing).
   • Fix: Use Alert::flash() for stateless redirects or ensure session middleware is loaded.

2. Alert Overwriting

   • Persistent alerts (->persist()) stack if triggered multiple times. Use Alert::replace() to clear previous alerts:

     Alert::replace()->success('New message.');
     

3. View Not Rendering

   • Forgetting @alerts in your layout will hide alerts. Verify the directive is included in all relevant views.

4. Custom Types Not Working

   • Ensure custom alert types are registered in config/alerts.php:

     'types' => [
         'custom-type' => 'Custom Alert',
     ],
     

Debugging Tips

• Check Session Data: Dump the session to verify alerts are stored:

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

• Clear Alerts Manually: Force-clear alerts in Tinker:

  php artisan tinker
  >>> \Prologue\Alerts\Facades\Alert::clear();
  

Extension Points

1. Custom Alert Classes Extend the Alert class for reusable logic:

   class CustomAlert extends Alert
   {
       public static function notify($message)
       {
           return static::info($message)->persist();
       }
   }
   

2. Alert Events Listen for alert events (e.g., alert.created):

   Alert::created(function ($alert) {
       Log::info("Alert triggered: {$alert->type}");
   });
   

3. Database Storage For persistent alerts beyond sessions, integrate with a database:

   Alert::success('Database alert')->storeIn('alerts_table');
   

   (Requires custom implementation or a package like prologue/alerts-database.)

4. Localization Localize alert messages by publishing language files:

   php artisan vendor:publish --provider="Prologue\Alerts\AlertsServiceProvider" --tag="lang"
   

   Then update resources/lang/{locale}/alerts.php.