PHP SDK

messagebird/sdk to oficjalny SDK PHP dla Bird API: typowana, ręcznie napisana warstwa nad generowaną warstwą transportową. Wymaga PHP 8.2+ i działa synchronicznie; HTTP przechodzi przez dowolny klient PSR-18, który już masz (Guzzle, Symfony HttpClient, …), wykrywany automatycznie. Ta strona dotyczy samego klienta; aby wysłać e-mail od początku do końca, zacznij od szybkiego startu z e-mailem w PHP.

Instalacja

composer require messagebird/sdk

Pakiet jest opublikowany jako messagebird/sdk na Packagist.

Tworzenie klienta

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

Wymagany jest tylko klucz API. Region jest ustalany na podstawie prefiksu bk_{region}_ klucza (klucz bk_eu1_… kieruje do https://eu1.platform.bird.com), więc większość klientów tworzy się, podając sam klucz; reguły opisano w sekcji wnioskowanie regionu. baseUrl nadpisuje region całkowicie (lokalne lub samodzielnie hostowane środowisko). Wartości domyślne kanału ustawione tutaj (na przykład email: new EmailDefaults(from: "hello@acme.com")) sprawiają, że to pole jest opcjonalne przy każdym wysyłaniu, a webhookSecret to sekret, za pomocą którego $bird->webhooks->unwrap() weryfikuje podpisy. Timeout per żądanie konfiguruj na kliencie PSR-18 przekazywanym do Bird. PSR-18 nie ma przenośnego timeoutu, więc ustawienie należy do transportu.

Pierwsze wywołanie

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

Wywołanie zwraca bezpośrednio wynik API: tutaj wiadomość e-mail z jej identyfikatorem em_*. Aby przejść pełny przykład krok po kroku, postępuj zgodnie z szybkim startem PHP.

Dwuwarstwowa architektura

SDK łączy warstwę generowaną z ręcznie utrzymywaną. Typy transportowe w MessageBird\Wire pochodzą ze specyfikacji OpenAPI Bird za pośrednictwem jane-php, dzięki czemu kształty żądań i odpowiedzi są zgodne z kontraktem. Ręcznie napisana warstwa zapewnia $bird->email->send(...), ponowne próby, idempotentność, paginację, obsługę błędów i weryfikację webhooków. Pola transportowe przechodzą dosłownie w snake_case, na przykład category i created_at. Tylko identyfikatory zdefiniowane przez SDK, w tym nazwy metod i opcji takie jak idempotencyKey, używają camelCase. SDK TypeScript, Go i Python mają tę samą architekturę; zobacz koncepcje SDK.

Automatyczna idempotentność i ponowne próby

Każda operacja modyfikująca (POST, PUT, PATCH, DELETE) otrzymuje automatycznie wygenerowany nagłówek Idempotency-Key. Ten sam klucz jest używany przy każdym ponowieniu, dzięki czemu zgodne żądania mogą otrzymać zachowaną odpowiedź. Ponawianie jest domyślnie włączone (maxRetries: 2): klient ponawia przejściowe błędy (429, 5xx z wyjątkiem 501 oraz błędy transportu PSR-18) z wykładniczo rosnącym opóźnieniem i losowym odchyleniem, uwzględniając nagłówek Retry-After serwera. Błędy deterministyczne (4xx, takie jak 401, 404, 422) nie są nigdy ponawiane. Informacje o własnych kluczach między oddzielnymi wywołaniami SDK i limitach ponownego zwracania odpowiedzi znajdziesz w sekcji Idempotencja. Nadpisz ustawienia idempotencji i ponowień dla wywołania:

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

Błędy

Nieudane wywołanie rzuca wyjątek. MessageBird\Exception\ApiException obejmuje każdą odpowiedź z błędem serwera i zawiera status (status HTTP), type (ogólna kategoria) oraz errorCode (stabilny kod E#####). Błąd transportu, który wyczerpie budżet ponownych prób, rzuca zamiast tego MessageBird\Exception\ConnectionException, ponieważ nie istnieje żadna odpowiedź HTTP. Oba rozszerzają MessageBird\Exception\BirdException, więc przechwytuj ten typ, aby obsłużyć każdy z nich.

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

Paginacja

Metody listujące zwracają leniwy Core\Page; iterowanie go za pomocą foreach automatycznie paginuje po kursorach, pobierając strony na żądanie:

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

Aby ręcznie sterować kursorem, fetch() zwraca pojedynczą stronę: jej data plus kursor do przodu nextCursor, który przekazujesz z powrotem jako starting_after, aby przejść dalej:

$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

Wyjście awaryjne

Endpointy, które nie mają jeszcze typowanej powierzchni, są dostępne przez $bird->get / post / put / patch / delete, z tą samą autoryzacją, ponownymi próbami, idempotentością i obsługą 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',
]);

Ścieżki znajdziesz w referencji API.

Webhooki

Zweryfikuj podpis Standard Webhooks dostarczonego webhooka i uzyskaj zdekodowane zdarzenie. Ustaw sekret podpisujący na kliencie (lub przekaż go per wywołanie) i przekaż surowe ciało żądania: podpis jest obliczany na surowych bajtach, więc parsowanie przed weryfikacją to klasyczny błąd webhookowy.

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

Następne kroki

• Szybki start z e-mailem w PHP: gotowy do uruchomienia przykład wysyłki od początku do końca.
• Koncepcje SDK: model ponownych prób, paginacji i regionów wspólny dla wszystkich SDK.
• Referencja API: wszystkie operacje z przykładami w PHP.