getting-started.md

Getting Started

CommonPHP Notifications sends application notifications through named channels backed by notification drivers.

Install

composer require comphp/notifications

In this monorepo, the package is available through the workspace path repository. The package depends on comphp/runtime for the common driver and service provider contracts.

Send A Notification

<?php

declare(strict_types=1);

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

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

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

if ($result->isSuccessful()) {
    echo 'Notification sent.';
}

Notifier::memory() uses ArrayNotificationDriver, which records deliveries in memory. It is useful for tests, local development, and examples. Production applications should register provider-specific drivers.

Register Channels

use CommonPHP\Notifications\ChannelRegistry;
use CommonPHP\Notifications\Notifier;

$notifier = new Notifier(
    ChannelRegistry::single('email', $emailDriver),
);

$notifier
    ->registerChannel('sms', $smsDriver)
    ->registerChannel('webhook', $webhookDriver);

Channel names are normalized to lowercase and may contain letters, numbers, dots, dashes, and underscores.

Template Notifications

$notifier->sendTemplate(
    template: 'auth.password-reset',
    data: ['url' => $resetUrl],
    channel: 'email',
    recipients: ['ada@example.com'],
    subject: 'Reset your password',
);

Template rendering is intentionally not owned by this package. Drivers may render templates themselves, or an application layer can create a final Notification body before sending.