README

Signature:
·························································································································································
:$$$$$$$$$$$$$$$AAA$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$iiii$$$$$$$$$$$$$$$$TTTTTTTTTTTTTTTTTTTTTTT$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$hhhhhhh$$$$$$$$$$$$$:
:$$$$$$$$$$$$$$A:::A$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$i::::i$$$$$$$$$$$$$$$T:::::::::::::::::::::T$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$h:::::h$$$$$$$$$$$$$:
:$$$$$$$$$$$$$A:::::A$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$iiii$$$$$$$$$$$$$$$$T:::::::::::::::::::::T$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$h:::::h$$$$$$$$$$$$$:
:$$$$$$$$$$$$A:::::::A$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$T:::::TT:::::::TT:::::T$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$h:::::h$$$$$$$$$$$$$:
:$$$$$$$$$$$A:::::::::A$$$$$$$$$$rrrrr$$$rrrrrrrrr$$iiiiiii$$$$$ssssssssssTTTTTT$$T:::::T$$TTTTTTeeeeeeeeeeee$$$$$$$$cccccccccccccccch::::h$hhhhh$$$$$$$:
:$$$$$$$$$$A:::::A:::::A$$$$$$$$$r::::rrr:::::::::r$i:::::i$$$ss::::::::::s$$$$$$$T:::::T$$$$$$ee::::::::::::ee$$$$cc:::::::::::::::ch::::hh:::::hhh$$$$:
:$$$$$$$$$A:::::A$A:::::A$$$$$$$$r:::::::::::::::::r$i::::i$ss:::::::::::::s$$$$$$T:::::T$$$$$e::::::eeeee:::::ee$c:::::::::::::::::ch::::::::::::::hh$$:
:$$$$$$$$A:::::A$$$A:::::A$$$$$$$rr::::::rrrrr::::::ri::::i$s::::::ssss:::::s$$$$$T:::::T$$$$e::::::e$$$$$e:::::ec:::::::cccccc:::::ch:::::::hhh::::::h$:
:$$$$$$$A:::::A$$$$$A:::::A$$$$$$$r:::::r$$$$$r:::::ri::::i$$s:::::s$$ssssss$$$$$$T:::::T$$$$e:::::::eeeee::::::ec::::::c$$$$$ccccccch::::::h$$$h::::::h:
:$$$$$$A:::::AAAAAAAAA:::::A$$$$$$r:::::r$$$$$rrrrrrri::::i$$$$s::::::s$$$$$$$$$$$T:::::T$$$$e:::::::::::::::::e$c:::::c$$$$$$$$$$$$$h:::::h$$$$$h:::::h:
:$$$$$A:::::::::::::::::::::A$$$$$r:::::r$$$$$$$$$$$$i::::i$$$$$$$s::::::s$$$$$$$$T:::::T$$$$e::::::eeeeeeeeeee$$c:::::c$$$$$$$$$$$$$h:::::h$$$$$h:::::h:
:$$$$A:::::AAAAAAAAAAAAA:::::A$$$$r:::::r$$$$$$$$$$$$i::::i$ssssss$$$s:::::s$$$$$$T:::::T$$$$e:::::::e$$$$$$$$$$$c::::::c$$$$$ccccccch:::::h$$$$$h:::::h:
:$$$A:::::A$$$$$$$$$$$$$A:::::A$$$r:::::r$$$$$$$$$$$i::::::is:::::ssss::::::s$$$TT:::::::TT$$e::::::::e$$$$$$$$$$c:::::::cccccc:::::ch:::::h$$$$$h:::::h:
:$$A:::::A$$$$$$$$$$$$$$$A:::::A$$r:::::r$$$$$$$$$$$i::::::is::::::::::::::s$$$$T:::::::::T$$$e::::::::eeeeeeee$$$c:::::::::::::::::ch:::::h$$$$$h:::::h:
:$A:::::A$$$$$$$$$$$$$$$$$A:::::A$r:::::r$$$$$$$$$$$i::::::i$s:::::::::::ss$$$$$T:::::::::T$$$$ee:::::::::::::e$$$$cc:::::::::::::::ch:::::h$$$$$h:::::h:
:AAAAAAA$$$$$$$$$$$$$$$$$$$AAAAAAArrrrrrr$$$$$$$$$$$iiiiiiii$$sssssssssss$$$$$$$TTTTTTTTTTT$$$$$$eeeeeeeeeeeeee$$$$$$cccccccccccccccchhhhhhh$$$$$hhhhhhh:
:$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$:
:$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$:
:$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$:
:$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$:
·························································································································································
 _______   _______   ________   ______   __       __  ________  _______  
/       \ /       \ /        | /      \ /  \     /  |/        |/       \ 
$$$$$$$  |$$$$$$$  |$$$$$$$$/ /$$$$$$  |$$  \   /$$ |$$$$$$$$/ $$$$$$$  |
$$ |  $$ |$$ |__$$ |$$ |__    $$ |__$$ |$$$  \ /$$$ |$$ |__    $$ |__$$ |
$$ |  $$ |$$    $$< $$    |   $$    $$ |$$$$  /$$$$ |$$    |   $$    $$< 
$$ |  $$ |$$$$$$$  |$$$$$/    $$$$$$$$ |$$ $$ $$/$$ |$$$$$/    $$$$$$$  |
$$ |__$$ |$$ |  $$ |$$ |_____ $$ |  $$ |$$ |$$$/ $$ |$$ |_____ $$ |  $$ |
$$    $$/ $$ |  $$ |$$       |$$ |  $$ |$$ | $/  $$ |$$       |$$ |  $$ |
$$$$$$$/  $$/   $$/ $$$$$$$$/ $$/   $$/ $$/      $$/ $$$$$$$$/ $$/   $$/

Un package Laravel élégant pour intégrer l'API Nimba SMS, permettant l'envoi de SMS, la gestion des contacts et des groupes, les vérifications par code, et bien plus encore.

Fonctionnalités

📱 Envoi de SMS simple et programmé
👥 Gestion complète des contacts et des groupes
✅ Système de vérification par code
📊 Rapports de livraison et statistiques
🔄 Gestion robuste des erreurs via des exceptions spécialisées
🛡️ Gestion configurable de la vérification SSL (désactivation en développement)
🔄 Compatible avec Laravel 10.x et 11.x

Prérequis

PHP 8.x
Laravel 10.x ou 11.x
Compte Nimba SMS avec identifiants API

Installation

Installez le package via Composer :

composer require aristech/nimbasms

Publiez le fichier de configuration :

php artisan vendor:publish --tag=config

Configuration

Ajoutez vos identifiants Nimba SMS dans votre fichier .env :

NIMBA_SMS_SERVICE_ID=votre_service_id
NIMBA_SMS_SECRET=votre_secret
NIMBA_SMS_BASE_URL=https://api.nimbasms.com/
# Désactivez la vérification SSL en développement (à activer en production)
NIMBA_SMS_SSL_VERIFY=false

Le fichier de configuration config/nimbasms.php est disponible pour personnalisation :

return [
    'serviceId' => env('NIMBA_SMS_SERVICE_ID', ''),
    'secret'    => env('NIMBA_SMS_SECRET', ''),
    'baseUrl'   => env('NIMBA_SMS_BASE_URL', 'https://api.nimbasms.com/'),
    // Contrôle de la vérification SSL (important en production)
    'ssl_verify'=> filter_var(env('NIMBA_SMS_SSL_VERIFY', true), FILTER_VALIDATE_BOOLEAN),
];

Utilisation

Injection de Dépendance

Le package utilise l'injection de dépendance de Laravel. Vous pouvez injecter le client SMS via l'interface :

use Aristech\NimbaSms\Contracts\SmsClientInterface;

class SmsController extends Controller
{
    protected SmsClientInterface $smsClient;

    public function __construct(SmsClientInterface $smsClient)
    {
        $this->smsClient = $smsClient;
    }
}

Envoi de SMS

try {
    $response = $this->smsClient->send(
        'MonEntreprise',           // Nom de l'expéditeur
        ['+22457123456'],          // Liste des destinataires
        'Votre message ici'        // Contenu du message
    );
    
    // Traitement de la réponse
    return response()->json($response);
    
} catch (NimbaSmsException $e) {
    // Gestion des erreurs
    return response()->json([
        'error' => $e->getMessage(),
        'details' => $e->getErrorDetails()
    ], 400);
}

Gestion des Contacts

// Création d'un contact
$response = $smsClient->createContact(
    'John Doe',                   // Nom
    ['Clients', 'VIP'],           // Groupes
    '+22457123456'                // Numéro
);

// Mise à jour d'un contact
$response = $smsClient->updateContact(
    'contact_id',
    'John Doe Updated',
    ['Clients'],
    '+22457123456'
);

// Suppression d'un contact
$response = $smsClient->deleteContact('contact_id');

// Liste des contacts
$contacts = $smsClient->getContacts();

Gestion des Groupes

// Création d'un groupe
$response = $smsClient->createGroup('Nouveau Groupe');

// Mise à jour d'un groupe
$response = $smsClient->updateGroup('group_id', 'Nouveau Nom');

// Suppression d'un groupe
$response = $smsClient->deleteGroup('group_id');

// Liste des groupes
$groups = $smsClient->getGroups();

Vérification par Code

// Envoi d'un code de vérification
$response = $smsClient->createVerification('+22457123456');

// Validation du code
$response = $smsClient->validateVerification(
    '+22457123456',              // Numéro
    '123456'                     // Code reçu
);

SMS Programmés

$response = $smsClient->scheduleSms(
    'MonEntreprise',             // Expéditeur
    ['+22457123456'],            // Destinataires
    'Message programmé',         // Contenu
    '2024-12-31 23:59:59'         // Date d'envoi
);

Rapports

// Récupération d'un message spécifique
$message = $smsClient->getMessageById('message_id');

// Rapport de livraison d'un message
$report = $smsClient->getDeliveryReport('message_id');

// Liste des messages envoyés
$messages = $smsClient->getMessages();

Gestion des Erreurs

Le package gère les erreurs de manière robuste via l'exception NimbaSmsException :

try {
    $response = $smsClient->send($sender, $recipients, $message);
} catch (NimbaSmsException $e) {
    // Code d'erreur spécifique
    $errorCode = $e->getErrorCode();
    
    // Détails supplémentaires de l'erreur
    $details = $e->getErrorDetails();
    
    // Message d'erreur
    $message = $e->getMessage();
    
    // Log de l'erreur
    Log::error('Erreur Nimba SMS', [
        'message' => $message,
        'code' => $errorCode,
        'details' => $details
    ]);
}

Tests

Pour exécuter les tests du package :

composer test

Le package utilise Orchestra Testbench pour la configuration du testing.

Changelog

Consultez CHANGELOG.md pour les détails des modifications récentes.

Contribution

Les contributions sont les bienvenues ! Pour plus de détails, consultez CONTRIBUTING.md.

Sécurité

Si vous découvrez une faille de sécurité, merci d'envoyer un email à aristechdev@gmail.com.

Crédits

Licence

Le package Nimba SMS est distribué sous licence MIT.

Support

Pour toute question ou assistance :

📧 Email: aristechdev@gmail.com
📚 Documentation officielle Nimba SMS

aristech / nimbasms

Maintainers

Details