Notifications Laravel Package

Getting Started

Begin by installing the package via Composer (composer require illuminate/notifications) in a Laravel 13+ application. While this package is a subtree split—not intended for direct standalone use—it's essential for developers extending Laravel’s notification system. In practice, you’ll interact with notifications through Laravel’s Notification facade (use Illuminate\Support\Facades\Notification;) or the Notifiable trait. The first use case is sending a simple notification (e.g., MailMessage) to a user:

Notification::send($user, new OrderShipped($order));

Check app/Notifications for generated notification classes, and review resources/views/notifications for email templates.

Implementation Patterns

• Notification Classes: Create actionable, immutable notification classes (e.g., InvoicePaid, Alert) implementing Via methods (mail, database, broadcast, slack, etc.).
• Via Pipeline: Define delivery channels in via($notifiable)—the system automatically routes via each channel (e.g., mail, database, Pusher).
• Asynchronous Sending: Use Notification::queue() to dispatch notifications via the queue worker (requires queue channel and a configured queue driver).
• Custom Channels: Implement Channel classes (e.g., SlackChannel) and register them in app/Providers/EventServiceProvider’s boot() method.
• ** conditional Routing**: Use shouldSend($notifiable, $channel) to skip channel-specific delivery (e.g., don’t email if user opted out).
• Testing: Mock Notification::fake() to assert notifications were sent, queued, or not sent—ideal for integration tests.

Gotchas and Tips

• Subtree Split Warning: This package is not meant to be required directly in non-Laravel apps; it’s tightly coupled to Laravel’s container and ecosystem. Use the full laravel/framework instead unless patching core.
• Missing View Overrides: Email notifications rely on default vendor:publish --tag=laravel-notifications. If views aren’t rendering, check resources/views/notifications/ and ensure toMail() returns a MailMessage with correct properties.
• Queue Failures: Notifications queued via queue() are stored in jobs table. Monitor failed jobs with php artisan queue:fail—notifications don’t auto-retry unless retry_until is set in config/queue.
• Channel Dependencies: Missing channels cause silent failures. Ensure illuminate/broadcasting, illuminate/mail, etc., are available (via Laravel’s meta-package) and service providers are registered.
• Debugging: Enable notification logging by overriding logError() in your notification class or use Notification::logChannels() for runtime diagnostics.
• Custom Channel Factories: If implementing a custom channel (e.g., SMS), inject providers like SmsGateway into the channel—don’t hardcode dependencies in to{Channel}().