README

CommonPHP Notifications provides driver-based notification delivery for CommonPHP applications. It defines the common structure for sending application notifications through channels such as email, SMS, webhooks, and third-party messaging APIs.

The package is centered around a notifier service, notification objects, recipients, delivery results, and channel-specific drivers. It is intended to provide the shared notification layer while keeping provider-specific behavior in separate driver packages.

Requirements

• PHP ^8.5
• comphp/runtime:^0.3

Installation

Once this package is available through your Composer repositories, install it with:

composer require comphp/notifications

Usage

<?php

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

$notifier = new Notifier();

$notification = new Notification(
    subject: 'Welcome',
    body: 'Thanks for signing up.',
    recipients: ['user@example.com']
);

$notifier->send($notification, channel: 'email');

$notifications->sendTemplate(
    template: 'auth.password-reset',
    data: ['url' => $url],
    channel: 'email',
    recipients: [...]
);

$notifications->channel('sms')->send(
    new Notification(
        body: 'Your verification code is 123456.',
        recipients: ['+15555555555'],
    )
);

Package Notes

This package should define the core notification contracts, notifier service, notification message objects, recipients, delivery results, and driver integration points.

Provider-specific delivery belongs in separate driver packages, such as SMTP, SendGrid, Twilio, Slack, Teams, or webhook notification drivers.

The package should focus on application notifications, not general-purpose chat, queueing, marketing automation, or real-time messaging.

Error Handling

Notification creation, channel lookup, driver resolution, delivery, and provider failures should throw CommonPHP notification exceptions instead of returning ambiguous false values.

Drivers should return structured delivery results when a notification was processed and should throw exceptions when delivery cannot be attempted safely.

Documentation

• Documentation index
• Usage
• Testing
• Contributing
• Security

License

MIT. See LICENSE.md.