README

A package for Laravel that bundles notifications sent within a specified delay for a single user.

📖 Table of contents

1. Installation
2. Usage
   1. Limitations
   2. Changing the delay
   3. Specify the channels to bundle Contributing
3. License
4. OWOW

⚙️ Installation

Installing this package can be done by using Composer:

composer require owowagency/laravel-notification-bundler

🛠️ Usage

Here is a simple example of how to use this package.

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;
use Illuminate\Support\Collection;
use Owowagency\NotificationBundler\BundlesNotifications;
use Owowagency\NotificationBundler\ShouldBundleNotifications;

class BundledMailNotification extends Notification implements ShouldBundleNotifications, ShouldQueue
{
    use BundlesNotifications, Queueable;

    public function __construct(public string $name)
    {
        //
    }

    /**
     * The channels the notification should be sent on.
     */
    public function via(object $notifiable): array
    {
        return ['mail'];
    }

    /**
     * Get the mail representation of the notification.
     * This replaces the original `toMail` method and adds the $notifications 
     * collection as the last parameter.
     */
    public function toMailBundle(object $notifiable, Collection $notifications)
    {
        $message = (new MailMessage)
            ->subject('Bundle');

        foreach ($notifications as $notification) {
            $message->line("$notification->name was bundled.");
        }

        return $message;
    }

    /**
     * Returns the identifier for the bundle.
     * This is used to determine which notifications should be bundled together.
     * This also means that different notifications can be bundled together.
     */
    public function bundleIdentifier(object $notifiable): string
    {
        return "user_$notifiable->id";
    }
}

Limitations

Because of limitations in Laravel, the database channel must implicitly use the toArray, or toDatabase method. To get the notifications in those functions, you can use the getBundle() method.

public function toDatabase(object $notifiable): array
{
    $notifications = $this->getBundle();
    return ['names' => $notifications->pluck('name')->toArray()];
}

When you want to add custom middleware, it is important to always apply the bundle middleware first. If you don't do this, your notification could be bundled with a another notification later on, which can cause unexpected results.

class CustomMiddlewareNotification extends Notification implements ShouldBundleNotifications, ShouldQueue
{
    use BundlesNotifications {
        middleware as bundledMiddleware;
    }
    
    // ...
    
    public function middleware(object $notifiable): array
    {
        return [
            ...$this->bundledMiddleware($notifiable), // First apply the bundled middleware.
            StopExecution::class, // Then apply your own middleware.
        ];
    }
}

Changing the delay

By default, the delay is set to 30 seconds. You can change this delay by publishing the config file and changing the bundle_notifications_after_seconds value.

php artisan vendor:publish --provider="Owowagency\NotificationBundler\NotificationBundlerServiceProvider" --tag="config"

To change it per notification, the bundleDelay() method can be used.

public function bundleDelay(object $notifiable): int|\DateTimeInterface
{
    return 60;
}

To take even more control, you can use the withDelay() method to specify a delay per channel.

public function withDelay(object $notifiable): array
{
    return [
        'mail' => 30,
        'sms' => 60,
    ];
}

Specify the channels to bundle

By default, all channels are bundled. You can change this by using the bundleChannels() method.

public function bundleChannels(): array
{
    return ['mail'];
}

🫶 Contributing

Please see CONTRIBUTING for details.

📜 License

The MIT License (MIT). Please see License File for more information.

This package has been brought to you with much love by the wizkids of OWOW. Do you like this package? We’re still looking for new talent and Wizkids. So do you want to contribute to open source, while getting paid? Apply now.