README

notification/php

PHP 8.3+ client SDK for the hosted aice-notification service. A thin HTTP client — sendEmail/sendSms — plus typed request/receipt DTOs, a typed exception hierarchy, and a MockNotificationClient for consumer tests. No provider credentials (Brevo, SMTP, Novocom, …) live in this SDK or your process — the hosted notification-server holds them; this client only ever holds a bearer API key.

This SDK delivers a payload; it does not know what the payload means. No OTP issuance, no templating, no retries/queues — see ARCHITECTURE.md.

Install

This package is not yet published to a package registry. Consume it via a Composer VCS repository entry pointing at this repo, the same way other in-house PHP clients (e.g. aice-lab/payment) are consumed:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@gitlab.com:aice-lab/notification/php.git"
        }
    ],
    "require": {
        "aice-lab/notification": "dev-main"
    }
}

composer require aice-lab/notification:dev-main

Once a tagged release exists, pin to it (e.g. ^0.1) instead of dev-main. A group-wide Composer package registry (composer require aice-lab/notification with no repositories entry) may replace this once the group registry is wired up for this package.

Requires PHP 8.3+, ext-json, ext-curl.

Quickstart

use AiceLab\Notification\HttpNotificationClient;
use AiceLab\Notification\Dto\EmailRequest;
use AiceLab\Notification\Dto\SmsRequest;
use AiceLab\Notification\Exceptions\{
    InvalidRecipientException,
    InvalidPayloadException,
    UnauthorizedException,
    RateLimitedException,
    QuotaExceededException,
    ProviderUnavailableException,
    InternalException,
    TransportException,
    NotificationException,
};

$client = new HttpNotificationClient('https://notification.your-tenant.example', $apiKey);

try {
    $receipt = $client->sendEmail(new EmailRequest('user@example.com', 'Your link', 'Open https://app.example/verify?t=...'));
    // $receipt->deliveryId, $receipt->status
} catch (RateLimitedException|QuotaExceededException $e) {
    // $e->retryAfterSeconds
} catch (InvalidRecipientException|InvalidPayloadException|UnauthorizedException|ProviderUnavailableException|InternalException|TransportException $e) {
    // $e->errorCode, $e->getMessage()
} catch (NotificationException $e) {
    // base class — catches anything not enumerated above
}

sendSms(new SmsRequest($to, $message)) follows the same shape and throws the same exception set.

For consumer tests, use MockNotificationClient in place of HttpNotificationClient — it implements the same NotificationClientInterface, records the last request, and lets you script onSendEmail/onSendSms.

Server-to-server, BYO-key

HttpNotificationClient calls a hosted notification-server over HTTPS with a bearer API key you supply. This is a server-to-server binding only — the API key must never reach a browser or mobile client. Provider credentials (Brevo, SMTP, Novocom, …) never live in this SDK or your process; they live on the notification-server you point this client at.

Status

License

Source: FSL-1.1-Apache-2.0 (see LICENSE).

Contributing

See CONTRIBUTING.md.

Reporting security issues

See SECURITY.md. Do not open public issues for vulnerabilities.

This is a snapshot generated from GitLab. For the live README, see the project page.