Laravel Notify Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tylercd100/laravel-notify
   php artisan vendor:publish --provider="Tylercd100\Notify\Providers\NotifyServiceProvider"
   

   • Publishes config/notify.php for channel configuration.

2. First Use Case: Send a basic log message to all configured channels (e.g., Slack, Email):

   use Tylercd100\Notify\Facades\Notify;
   
   Notify::info("User created successfully", ['user_id' => 123]);
   

   • Replace info with debug, warning, error, etc., based on severity.

3. Channel-Specific Usage: Add channel aliases to config/app.php (e.g., "Slack" => Tylercd100\Notify\Facades\Slack::class). Use directly:

   Slack::warning("Database connection failed!");
   

Implementation Patterns

Core Workflows

1. Log-Level Routing:

   • Use severity levels (debug, info, warning, error, etc.) to route messages to specific channels.
   • Example: Configure notify.php to send error messages to Slack but debug messages only to logs.

2. Contextual Data:

   • Attach structured data (e.g., user IDs, timestamps) via the second argument:

     Notify::error("Failed to process payment", ['user_id' => 456, 'amount' => 99.99]);
     

   • Channels like Slack/Email render this as formatted output (e.g., JSON or key-value pairs).

3. Channel-Specific Facades:

   • For granular control, use dedicated facades (e.g., Pushover::critical()).
   • Ideal for services with unique features (e.g., SMS character limits in Plivo).

4. Event-Driven Notifications:

   • Trigger notifications in event listeners or controllers:

     public function handle(InvoicePaid $event) {
         Notify::info("Invoice #{$event->invoice->id} paid", ['user' => $event->user]);
     }
     

5. Conditional Notifications:

   • Check config or environment before sending:

     if (config('notify.channels.slack.enabled')) {
         Slack::info("New user registered");
     }
     

Integration Tips

• Monolog Compatibility:

  • Leverage Monolog’s handlers (e.g., StreamHandler for local logs) alongside laravel-notify.
  • Example: Add a notify.php handler:

    'handlers' => [
        'slack' => [
            'driver' => 'slack',
            'webhook_url' => env('SLACK_WEBHOOK_URL'),
        ],
        'log' => [
            'driver' => 'monolog',
            'path' => storage_path('logs/notify.log'),
        ],
    ],
    

• Environment-Specific Config:

  • Use .env variables for sensitive data (e.g., SLACK_WEBHOOK_URL).
  • Override notify.php per environment (e.g., config/notify-staging.php).

• Testing:

  • Mock facades in PHPUnit:

    $this->mock(Notify::class)->shouldReceive('info')->once();
    

  • Use Notify::shouldReceive() for channel-specific assertions.

Gotchas and Tips

Pitfalls

1. Deprecated Features:

   • Laravel 5.x: Version 1.x is outdated; upgrade to 4.x for Laravel 7/8.
   • HipChat/Sentry: Migrate to Slack/Sentry SDK v3.x (see release notes).

2. Context Formatting:

   • Some channels (e.g., SMS) truncate long messages. Configure sms_limit in notify.php:

     'sms_limit' => 160, // Default for Twilio/Plivo
     

3. Email Content-Type:

   • Ensure text/html is set for emails (fixed in v1.8.2+). If using custom templates, verify the LineFormatter in config/notify.php:

     'formatters' => [
         'line' => \Monolog\Formatter\LineFormatter::class,
     ],
     

4. Facade Aliases:

   • Forgetting to add aliases to config/app.php will cause ClassNotFound errors for Slack, Pushover, etc.

5. Rate Limiting:

   • Channels like Slack may throttle messages. Use notify.php to batch or debounce:

     'slack' => [
         'driver' => 'slack',
         'rate_limit' => 5, // Messages per minute
     ],
     

Debugging

1. Log Inspection:

   • Check storage/logs/laravel.log for unhandled exceptions or malformed messages.
   • Enable debug mode in notify.php:

     'debug' => env('APP_DEBUG', false),
     

2. Channel-Specific Issues:

   • Slack: Verify webhook URLs and permissions. Test with:

     curl -X POST -H 'Content-type: application/json' --data '{"text":"Test"}' $SLACK_WEBHOOK_URL
     

   • Email: Check SMTP settings and spam folders. Use Mailgun facade for API-based emails:

     Mailgun::send('welcome@example.com', 'Hello from Mailgun!');
     

3. Context Serialization:

   • Non-serializable objects (e.g., closures) in context will throw errors. Use arrays or JSON:

     Notify::info("User data", ['role' => $user->role->name]); // OK
     Notify::info("User data", ['role' => $user->role]); // May fail
     

Extension Points

1. Custom Handlers:

   • Extend Tylercd100\Notify\Handlers\BaseHandler to add new channels (e.g., Discord, Telegram).
   • Register in config/notify.php:

     'handlers' => [
         'discord' => [
             'driver' => 'discord',
             'webhook_url' => env('DISCORD_WEBHOOK_URL'),
         ],
     ],
     

2. Formatter Overrides:

   • Replace the default LineFormatter with a custom formatter (e.g., for JSON output):

     'formatters' => [
         'json' => \Monolog\Formatter\JsonFormatter::class,
     ],
     

3. Middleware:

   • Add middleware to filter or modify messages before sending:

     // app/Providers/NotifyServiceProvider.php
     public function boot() {
         Notify::extend('custom', function($app) {
             return new CustomHandler($app['log']);
         });
     }
     

4. Queueing:

   • Offload notifications to queues (e.g., database or redis) for async processing:

     // config/notify.php
     'queue' => 'high',
     

   • Requires Laravel’s queue system and a NotifyJob implementation.