ipfsoftwares/notify-africa-php

Modern PHP SDK for the Notify Africa SMS HTTP API.

dev-main / 1.0.x-dev 2025-12-08 07:24 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
• guzzlehttp/guzzle: ^7.9
• psr/log: ^3.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.48.2
• ergebnis/data-provider: ^3.6.0
• ergebnis/license: ^2.7.0
• ergebnis/php-cs-fixer-config: ^6.57.0
• ergebnis/phpstan-rules: ^2.12.0
• ergebnis/phpunit-slow-test-detector: ^2.20.0
• fakerphp/faker: ^1.24.1
• infection/infection: ~0.27.11
• phpstan/extension-installer: ^1.4.3
• phpstan/phpstan: ^2.1.32
• phpstan/phpstan-deprecation-rules: ^2.0.3
• phpstan/phpstan-phpunit: ^2.0.8
• phpstan/phpstan-strict-rules: ^2.0.7
• phpunit/phpunit: ^10.5.45
• rector/rector: ^2.2.3
• roave/backward-compatibility-check: ^8.6.0
• tomasvotruba/type-coverage: ^2.0.2

MIT

• Notify Africa

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:

Option	Type	Description	Default
apiToken	string	Required Notify Africa API token	—
baseUri	string	Base API URL	https://api.notify.africa
timeout	float	Request timeout (seconds)	10.0
connectTimeout	float	Connection timeout (seconds)	5.0
logger	LoggerInterface	Optional PSR-3 logger	Psr\Log\NullLogger

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.