PHP SDK

messagebird/sdk is de officiële PHP SDK voor de Bird API: een getypte, handgeschreven laag bovenop een gegenereerde wirelaag. Het richt zich op PHP 8.2+ en is synchroon; HTTP gaat via elke PSR-18-client die je al hebt (Guzzle, Symfony HttpClient, …), automatisch ontdekt. Deze pagina behandelt de client zelf; om end-to-end e-mail te versturen, begin je met de PHP e-mail-quickstart.

Installeren

composer require messagebird/sdk

Het pakket is gepubliceerd als messagebird/sdk op Packagist.

Een client aanmaken

$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()
);

Alleen de API-sleutel is vereist. De regio wordt afgeleid uit het bk_{region}_-prefix van de sleutel (een bk_eu1_…-sleutel routeert naar https://eu1.platform.bird.com), dus de meeste clients worden aangemaakt met alleen de sleutel; zie regio-afleiding voor de regels. baseUrl overschrijft de regio volledig (lokaal of self-hosted). Kanaalstandaarden die je hier instelt (bijvoorbeeld email: new EmailDefaults(from: "hello@acme.com")) maken dat veld optioneel bij elk verzendverzoek, en webhookSecret is het geheim waarmee $bird->webhooks->unwrap() verifieert. Configureer een timeout per verzoek op de PSR-18-client die je doorgeeft aan Bird. PSR-18 heeft geen draagbare timeout, dus het transport beheert die instelling.

Eerste aanroep

$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();

De aanroep retourneert direct het API-resultaat: hier een e-mailbericht met zijn em_* id. Volg de PHP-quickstart voor een uitvoerbaar stappenplan.

Tweelaags ontwerp

De SDK combineert gegenereerde en handgeschreven lagen. De wiretypen onder MessageBird\Wire komen uit de OpenAPI-specificatie van Bird via jane-php, waardoor request- en responseshapes contractconform blijven. De handgeschreven laag biedt $bird->email->send(...), retries, idempotentie, paginering, fouten en webhookverificatie. Wirevelden worden letterlijk doorgegeven in snake_case, zoals category en created_at. Alleen SDK-gedefinieerde identifiers, waaronder methode- en optienamen zoals idempotencyKey, gebruiken camelCase. De TypeScript-, Go- en Python-SDK's delen deze architectuur; zie SDK-concepten.

Automatische idempotentie en retries

Elke mutatie (POST, PUT, PATCH, DELETE) krijgt een automatisch gegenereerde header Idempotency-Key. Dezelfde sleutel wordt bij elke herhaalpoging gebruikt, zodat overeenkomende verzoeken het bewaarde antwoord opnieuw kunnen krijgen. Automatisch opnieuw proberen staat standaard aan (maxRetries: 2): de client probeert tijdelijke fouten (429, 5xx behalve 501 en PSR-18-transportfouten) opnieuw met exponentieel oplopende wachttijden en willekeurige variatie, met inachtneming van de header Retry-After van de server. Deterministische fouten (4xx zoals 401, 404, 422) worden nooit opnieuw geprobeerd. Zie Idempotentie voor eigen sleutels over afzonderlijke SDK-aanroepen en de grenzen aan het opnieuw teruggeven van antwoorden. Overschrijf idempotentie en herhaalpogingen per aanroep:

$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),
);

Fouten

Een mislukte aanroep gooit een exception. MessageBird\Exception\ApiException dekt elk foutantwoord van de server en bevat status (de HTTP-status), type (de grove categorie) en errorCode (de stabiele E#####-code). Een transportfout die het retrybudget uitput, gooit in plaats daarvan MessageBird\Exception\ConnectionException omdat er geen HTTP-response bestaat. Beide extenden MessageBird\Exception\BirdException, dus vang die op om beide af te handelen.

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();
}

Paginering

Lijstmethoden retourneren een lazy Core\Page; itereren met foreach pagineert automatisch over cursors en haalt pagina's op wanneer nodig:

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

Voor handmatige cursorbesturing retourneert fetch() één pagina: de data plus de voorwaartse nextCursor, die je teruggeeft als starting_after om verder te gaan:

$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

Nooduitgang

Endpoints die nog niet op het getypte oppervlak staan, zijn bereikbaar via $bird->get / post / put / patch / delete, met dezelfde auth, retries, idempotentie en base-URL-afhandeling:

// 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',
]);

Vind de paden in de API-referentie.

Webhooks

Verifieer de Standard Webhooks-handtekening van een ontvangen webhook en haal het gedecodeerde event op. Stel het ondertekeningsgeheim in op de client (of geef het per aanroep mee), en geef de onbewerkte request body door: de handtekening is over de ruwe bytes, dus parsen vóór verificatie is de klassieke webhookfout.

// 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
}

Vervolgstappen

• PHP e-mail-quickstart: een uitvoerbare end-to-end-verzending.
• SDK-concepten: het retry-, paginerings- en regiomodel dat door alle SDK's wordt gedeeld.
• API-referentie: elke operatie, met PHP-voorbeelden.