README

A modern PHP 8.1+ SDK for integrating with the Notify Africa SMS HTTP API. This library provides a convenient, typed API for sending single or bulk SMS messages with robust error handling and first-class testing support.

Installation

composer require ipfsoftwares/notify-africa-php:dev-main

Quick Start

<?php

use NotifyAfrica\Sms\ClientConfig;
use NotifyAfrica\Sms\NotifyAfricaClient;
use NotifyAfrica\Sms\Request\SingleMessageRequest;

$config = new ClientConfig(
    apiToken: 'your-api-token',
    baseUri: 'https://api.notify.africa',
);

$client = new NotifyAfricaClient($config);

$response = $client->sendSingleMessage(
    new SingleMessageRequest(
        phoneNumber: '255689737459',
        message: 'Hello from SDK!',
        senderId: '137',
    )
);

printf('Message ID: %s', $response->getMessageId());

Features

• Typed configuration, request, and response objects
• Configurable timeouts and HTTP layer (Guzzle by default)
• Batch and single message support
• Domain-specific exceptions for authentication, validation, and HTTP issues
• PSR-3 logging integration

Usage

Sending a Single SMS

use NotifyAfrica\Sms\Request\SingleMessageRequest;

$response = $client->sendSingleMessage(
    new SingleMessageRequest(
        phoneNumber: '255689737459',
        message: 'Hello from SDK!',
        senderId: '137',
    )
);

echo $response->getMessageId();

Sending Batch SMS

use NotifyAfrica\Sms\Request\BatchMessageRequest;

$response = $client->sendBatchMessages(
    new BatchMessageRequest(
        phoneNumbers: ['255763765548', '255689737839'],
        message: 'Promotional offer',
        senderId: '137',
    )
);

echo $response->getBatchId();

Error Handling

Wrap calls in a try/catch block to handle failures:

use NotifyAfrica\Sms\Exception\AuthenticationException;
use NotifyAfrica\Sms\Exception\ValidationException;
use NotifyAfrica\Sms\Exception\HttpRequestException;

try {
    $client->sendSingleMessage($request);
} catch (AuthenticationException $exception) {
    // invalid token or insufficient permissions
} catch (ValidationException $exception) {
    // request payload issues
} catch (HttpRequestException $exception) {
    // network or unexpected API response
}

Configuration

ClientConfig accepts the following options:

Examples

The examples/ directory contains runnable scripts:

• examples/send_single.php
• examples/send_batch.php

Run them with:

php examples/send_single.php
php examples/send_batch.php

Testing

composer install
vendor/bin/phpunit --configuration test/Unit/phpunit.xml

License

MIT License. See LICENSE.md.