PHP SDK

messagebird/sdk è l'SDK PHP ufficiale SDK per Bird API: una superficie tipizzata, scritta a mano, sopra un livello wire generato. È rivolto a PHP 8.2+ ed è sincrono; HTTP passa attraverso qualsiasi client PSR-18 che hai già (Guzzle, Symfony HttpClient, …), individuato automaticamente. Questa pagina tratta il client stesso; per inviare un'email da un capo all'altro, inizia con la guida rapida email per PHP.

Installazione

composer require messagebird/sdk

Il pacchetto è pubblicato come messagebird/sdk su Packagist.

Costruire un client

$bird = new Bird(
    getenv('BIRD_API_KEY') ?: '',
    region: 'eu1',                                          // optional; overrides the region inferred from the key prefix
    maxRetries: 2,                                          // retry budget for transient failures (default 2)
    email: new EmailDefaults(from: 'hello@acme.com'),       // optional channel defaults, such as a default sender
    webhookSecret: getenv('BIRD_WEBHOOK_SECRET') ?: null,   // signing secret for $bird->webhooks->unwrap()
);

Solo la chiave API è obbligatoria. La regione viene dedotta dal prefisso bk_{region}_ della chiave (una chiave bk_eu1_… viene instradata verso https://eu1.platform.bird.com), quindi la maggior parte dei client si costruisce con la sola chiave; consulta deduzione della regione per le regole. baseUrl sovrascrive completamente la regione (locale o self-hosted). I valori predefiniti del canale impostati qui (ad esempio email: new EmailDefaults(from: "hello@acme.com")) rendono quel campo facoltativo in ogni invio, e webhookSecret è il segreto con cui $bird->webhooks->unwrap() verifica. Configura un timeout per richiesta sul client PSR-18 che passi a Bird. PSR-18 non ha un timeout portabile, quindi il trasporto gestisce questa impostazione.

Prima chiamata

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    subject: 'Hello from Bird',
    html: '<p>My first Bird email.</p>',
);
echo $message->getId(), ' ', $message->getStatus();

La chiamata restituisce direttamente il risultato API: in questo caso un messaggio email con il suo id em_*. Per una guida eseguibile, segui la guida rapida PHP.

Architettura a due livelli

L'SDK combina un livello generato e uno scritto a mano. I tipi wire sotto MessageBird\Wire derivano dalla specifica OpenAPI di Bird tramite jane-php, mantenendo le forme di richiesta e risposta conformi al contratto. Il livello scritto a mano fornisce $bird->email->send(...), retry, idempotenza, paginazione, errori e verifica dei webhook. I campi wire passano verbatim in snake_case, come category e created_at. Solo gli identificatori definiti da SDK, inclusi nomi di metodi e opzioni come idempotencyKey, usano camelCase. Gli SDK TypeScript, Go e Python condividono questa architettura; consulta i concetti SDK.

Idempotenza automatica e retry

Ogni mutazione (POST, PUT, PATCH, DELETE) riceve un header Idempotency-Key generato automaticamente. La stessa chiave viene riutilizzata a ogni tentativo, così le richieste corrispondenti possono riprodurre la risposta conservata. I tentativi automatici sono attivi per impostazione predefinita (maxRetries: 2): il client riprova gli errori transitori (429, 5xx tranne 501 ed errori di trasporto PSR-18) con attese esponenziali e variazioni casuali, rispettando l’header Retry-After del server. Gli errori deterministici (4xx come 401, 404, 422) non vengono mai ritentati. Per le chiavi personalizzate tra chiamate separate all’SDK e i limiti di riproduzione, consulta Idempotenza. Sovrascrivi le impostazioni di idempotenza e dei tentativi per ogni chiamata:

$bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    subject: 'Hello from Bird',
    html: '<p>My first Bird email.</p>',
    options: new RequestOptions(idempotencyKey: 'order-1234', maxRetries: 0),
);

Errori

Una chiamata fallita lancia un'eccezione. MessageBird\Exception\ApiException copre ogni risposta di errore del server e contiene status (lo status HTTP), type (la categoria generale) e errorCode (il codice E##### stabile). Un errore di trasporto che esaurisce il budget di retry lancia invece MessageBird\Exception\ConnectionException perché non esiste una risposta HTTP. Entrambi estendono MessageBird\Exception\BirdException, quindi cattura quello per gestire entrambi i casi.

try {
    $bird->email->send(
        from: 'Bird <onboarding@messagebird.dev>',
        to: ['delivered@messagebird.dev'],
        subject: 'Hello from Bird',
        html: '<p>My first Bird email.</p>',
    );
} catch (ApiException $e) {
    // The server returned an error response. $status is the HTTP status, $type
    // the coarse category, $errorCode the stable E##### code.
    echo $e->status, ' ', $e->errorCode ?? $e->type ?? 'error';
} catch (ConnectionException $e) {
    // All retry attempts failed, so no HTTP response is available.
    echo 'transport error: ', $e->getMessage();
}

Paginazione

I metodi di lista restituiscono un Core\Page lazy; iterarlo con foreach pagina automaticamente attraverso i cursori, recuperando le pagine su richiesta:

foreach ($bird->email->list(['status' => 'delivered']) as $message) {
    echo $message->getId(), "\n";
}

Per il controllo manuale del cursore, fetch() restituisce una singola pagina: i suoi data più il cursore di avanzamento nextCursor, che passi come starting_after per procedere:

$page = $bird->email->list(['status' => 'delivered'])->fetch();
foreach ($page->data as $message) {
    echo $message->getId(), "\n";
}
$next = $page->nextCursor; // pass back as starting_after to fetch the next page

Scappatoia

Gli endpoint non ancora presenti sulla superficie tipizzata sono raggiungibili tramite $bird->get / post / put / patch / delete, con la stessa autenticazione, gli stessi retry, idempotenza e gestione del base URL:

// The verb methods (get/post/put/patch/delete) run through the same auth,
// retries, idempotency, and base-URL handling as the typed methods; pass a
// path and, for writes, a body array.
$messages = $bird->get('/v1/sms/messages', query: ['limit' => 10]);
$created = $bird->post('/v1/sms/messages', body: [
    'from' => '+15557654321',
    'to' => '+15551234567',
    'text' => 'Your code is 123456.',
    'category' => 'authentication',
]);

Trova i percorsi nel reference API.

Webhook

Verifica la firma Standard Webhooks di un webhook ricevuto e ottieni l'evento decodificato. Imposta il signing secret sul client (o passalo per singola chiamata), e passa il body grezzo della richiesta: la firma è calcolata sui byte grezzi, quindi effettuare il parsing prima della verifica è il classico bug dei webhook.

// Pass the raw request body because parsing changes the bytes used to compute
// the signature.
$rawBody = file_get_contents('php://input') ?: '';
try {
    $event = $bird->webhooks->unwrap($rawBody, getallheaders());
    // $event is the decoded payload as an array; branch on $event['type'].
    echo $event['type'];
} catch (WebhookVerificationError) {
    http_response_code(400); // bad signature, stale timestamp, or missing/malformed headers
}

Prossimi passi

• Guida rapida email per PHP: un invio end-to-end eseguibile.
• Concetti SDK: il modello di retry, paginazione e regione condiviso tra gli SDK.
• Reference API: ogni operazione, con esempi PHP.