usage.md

Usage

The package has four common usage styles: direct Notification delivery, template delivery, channel-specific delivery, and multi-channel delivery.

Direct Delivery

use CommonPHP\Notifications\Notification;
use CommonPHP\Notifications\Notifier;

$notifier = Notifier::memory('email');

$result = $notifier->send(
    new Notification(
        subject: 'Invoice paid',
        body: 'Invoice INV-1001 has been paid.',
        recipients: ['billing@example.com'],
        metadata: ['invoice_id' => 'INV-1001'],
        tags: ['billing', 'invoice'],
    ),
    'email',
);

send() returns a DeliveryResult. It throws notification exceptions when the channel is missing, the notification cannot be delivered safely, or the driver fails unexpectedly.

Channel Facade

$notifier->channel('email')->send(
    new Notification(
        subject: 'Welcome',
        body: 'Thanks for joining.',
        recipients: ['ada@example.com'],
    ),
);

channel() returns a NotificationChannel wrapper around a named channel. It is useful when code naturally works within one delivery channel.

Template Delivery

$notifier->channel('email')->sendTemplate(
    'mail.weekly-summary',
    ['user' => $user, 'items' => $items],
    ['ada@example.com'],
    'Your weekly summary',
);

Template names and data are carried by the notification object. The core package does not prescribe a renderer.

Multi-Channel Delivery

$report = $notifier->sendToChannels(
    new Notification(
        body: 'Build finished.',
        recipients: [
            ['email' => 'ops@example.com', 'channel' => 'email'],
            ['phone' => '+15555555555', 'channel' => 'sms'],
        ],
    ),
    ['email', 'sms'],
);

if ($report->hasFailures()) {
    $report->throwIfFailed();
}

Generic recipients with no channel are eligible for every channel. Channel-specific recipients are only delivered through their matching channel.