subitosms / subitosms-php

dev-main 2026-09-26 20:40 UTC

Requires

• php: >=7.4

Requires (Dev)

• phpunit/phpunit: ^9.6

MIT

• api
• sms
• gateway
• subitosms

Published on Packagist.org on 2026-09-26 20:40 UTC

README

Client PHP leggero e senza dipendenze per il gateway HTTP di SubitoSMS.

Supporta invio singolo o multiplo, invio di prova, invio ritardato, verifica del credito e lettura dello stato di consegna.

Requisiti

• PHP 7.4 o successivo
• estensione OpenSSL abilitata (per le chiamate HTTPS predefinite)
• account creato su SubitoSMS.it

Installazione

Quando il pacchetto sarà pubblicato su Packagist:

composer require subitosms/subitosms-php

Durante lo sviluppo locale, dalla cartella del progetto:

composer install

Invio di un SMS

<?php

require 'vendor/autoload.php';

use SubitoSMS\Client;

$sms = new Client('la-tua-username', 'la-tua-password');

$shipmentId = $sms->send(
    'MIOBRAND',
    '[phone]',
    'Ciao da SubitoSMS!'
);

echo "Spedizione: {$shipmentId}";

Il valore restituito è l'ID della spedizione assegnato dal gateway.

Più destinatari

Passa un array (oppure una stringa con numeri separati da virgola). Ogni numero può iniziare con +; non inserire spazi o altri caratteri.

$shipmentId = $sms->send(
    'MIOBRAND',
    ['[phone]', '[phone]'],
    'Promemoria appuntamento domani alle 10:00.'
);

Invio di prova e ritardato

Per lo sviluppo usa true come quarto parametro: il gateway simula l'invio e non scala il credito. Il quinto parametro ritarda l'invio di un numero di minuti.

$shipmentId = $sms->send(
    'MIOBRAND',
    '[phone]',
    'Messaggio di prova',
    true,
    15
);

Credito residuo

$credit = $sms->balance();
$creditWithForeign = $sms->balance(true);

Stato della spedizione

foreach ($sms->status($shipmentId) as $delivery) {
    printf(
        "%s — stato %d: %s%s",
        $delivery->getDestination(),
        $delivery->getStatus(),
        $delivery->getDescription(),
        PHP_EOL
    );

    if ($delivery->isTerminal()) {
        // Stati terminali: -100, -50, 1, 16.
    }
}

Puoi anche configurare nell'area clienti una URL di callback: SubitoSMS le invia in POST id, dest e stato a ogni aggiornamento. La callback dovrebbe rispondere rapidamente; il gateway attende fino a 120 secondi.

Gestione degli errori

Il client segnala con SubitoSMS\Exception\ApiException una risposta del gateway non riconosciuta (ad esempio credito insufficiente), e con SubitoSMS\Exception\TransportException un problema nel raggiungere il gateway.

use SubitoSMS\Exception\ApiException;
use SubitoSMS\Exception\TransportException;

try {
    $shipmentId = $sms->send('MIOBRAND', '[phone]', 'Ciao');
} catch (TransportException $e) {
    // Problema di rete/HTTPS: l'invio potrebbe non essere arrivato al gateway.
} catch (ApiException $e) {
    // Risposta del gateway non valida o non accettata.
}

Non ritentare automaticamente un invio quando non sai se il gateway lo abbia ricevuto: potresti inviare un SMS duplicato. Conserva l'ID di ogni spedizione riuscita e usa status() o la callback per seguirne la consegna.

Esempi eseguibili

• examples/send.php: invio simulato a più destinatari.
• examples/status.php: credito e stato di una spedizione.

Sostituisci le credenziali e gli esempi di numero/ID prima di eseguirli.

Licenza

MIT. Vedi LICENSE.