notification-objects.md

Notification Objects

Notification is the immutable message object that drivers receive.

Fields

A notification can carry:

• id: a caller-provided id or a generated 32-character hex id;
• subject: optional short subject text;
• body: optional body text;
• recipients: zero or more Recipient objects or recipient payloads;
• template: optional template name;
• data: template or driver data;
• metadata: application and tracing context;
• tags: normalized unique labels;
• createdAt: creation time.

At least one of subject, body, or template must be present.

Creating Notifications

use CommonPHP\Notifications\Notification;

$notification = new Notification(
    subject: 'Welcome',
    body: 'Thanks for signing up.',
    recipients: ['ada@example.com'],
    metadata: ['source' => 'registration'],
    tags: ['welcome'],
);

Template notifications can be created with the named factory:

$notification = Notification::template(
    'auth.password-reset',
    ['ada@example.com'],
    ['url' => $url],
    subject: 'Reset your password',
);

Copy Methods

Notification mutation methods return new instances:

$localized = $notification
    ->withSubject('Bienvenue')
    ->withBody('Merci pour votre inscription.')
    ->withMetadata('locale', 'fr_CA')
    ->withTag('localized');

Other copy methods include withRecipients(), withRecipient(), usingTemplate(), withData(), withoutData(), withMetadata(), withoutMetadata(), and withoutTag().

Channel Recipient Filtering

Drivers normally use the recipient list for their channel:

$emailRecipients = $notification->recipientsForChannel('email');

This returns recipients whose channel is email plus recipients with no channel.