recipients.md

Recipients

Recipient represents one destination address plus optional display name, channel, and metadata.

Accepted Shapes

Recipients can be created directly:

use CommonPHP\Notifications\Recipient;

$recipient = new Recipient('ada@example.com', 'Ada Lovelace', 'email');

They can also be normalized from common array shapes:

Recipient::from(['email' => 'ada@example.com']);
Recipient::from(['phone' => '+15555555555', 'channel' => 'sms']);
Recipient::from(['url' => 'https://example.com/hook', 'channel' => 'webhook']);
Recipient::from(['to' => 'ops@example.com', 'name' => 'Operations']);

String, integer, and Stringable values are treated as addresses.

Convenience Factories

$email = Recipient::email('ada@example.com', 'Ada');
$phone = Recipient::phone('+15555555555');
$webhook = Recipient::webhook('https://example.com/hook');

Metadata

Recipient metadata is intended for driver-specific or application-specific context:

$recipient = Recipient::email('ada@example.com')
    ->withMetadata('user_id', 123);

$userId = $recipient->metadata('user_id');

withMetadata(), withoutMetadata(), and withChannel() return new recipient instances.

Validation

Recipient addresses cannot be empty or longer than Recipient::MAX_ADDRESS_LENGTH. Metadata keys must be non-empty strings. Channel names follow the same rules as notification channels.