PHP SDK

messagebird/sdk adalah SDK PHP resmi untuk Bird API: sebuah surface bertipe yang ditulis manual di atas wire layer yang di-generate. SDK ini menargetkan PHP 8.2+ dan bersifat sinkron; HTTP melewati klien PSR-18 apa pun yang sudah Anda miliki (Guzzle, Symfony HttpClient, …), ditemukan secara otomatis. Halaman ini membahas klien itu sendiri; untuk mengirim email secara menyeluruh, mulai dengan quickstart email PHP.

Instal

Contoh kode

composer require messagebird/sdk

Paket ini diterbitkan sebagai messagebird/sdk di Packagist.

Membuat klien

Contoh kode

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

Hanya kunci API yang wajib. Region disimpulkan dari prefiks bk_{region}_ pada kunci (kunci bk_eu1_… diarahkan ke https://eu1.platform.bird.com), sehingga sebagian besar klien dibuat hanya dengan kunci; lihat inferensi region untuk aturannya. baseUrl menimpa region sepenuhnya (lokal atau self-hosted). Default channel yang diatur di sini (misalnya email: new EmailDefaults(from: "hello@acme.com")) membuat field tersebut opsional pada setiap pengiriman, dan webhookSecret adalah secret yang digunakan $bird->webhooks->unwrap() untuk memverifikasi. Konfigurasikan timeout per permintaan pada klien PSR-18 yang Anda berikan ke Bird. PSR-18 tidak memiliki timeout portabel, jadi transport yang mengelola pengaturan ini.

Panggilan pertama

Contoh kode

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

Panggilan ini mengembalikan hasil API secara langsung: di sini berupa pesan email dengan em_* id-nya. Untuk panduan yang dapat dijalankan, ikuti quickstart PHP.

Desain dua lapis

SDK menggabungkan layer yang di-generate dan layer yang ditulis manual. Tipe wire di bawah MessageBird\Wire berasal dari spesifikasi OpenAPI Bird melalui jane-php, menjaga bentuk request dan response tetap sesuai kontrak. Layer yang ditulis manual menyediakan $bird->email->send(...), coba lagi, idempotensi, paginasi, kesalahan, dan verifikasi webhook. Field wire diteruskan apa adanya dalam snake_case, seperti category dan created_at. Hanya identifier yang didefinisikan SDK, termasuk nama method dan option seperti idempotencyKey, yang menggunakan camelCase. SDK TypeScript, Go, dan Python berbagi arsitektur ini; lihat konsep SDK.

Idempotensi dan coba lagi otomatis

Setiap mutasi (POST, PUT, PATCH, DELETE) mendapatkan header Idempotency-Key yang dibuat otomatis. Kunci yang sama digunakan kembali pada setiap percobaan ulang agar permintaan yang cocok dapat memutar ulang respons yang disimpan. Percobaan ulang aktif secara default (maxRetries: 2): klien mencoba kembali kegagalan sementara (429, 5xx kecuali 501, dan kesalahan transport PSR-18) dengan jeda eksponensial yang diberi variasi acak, serta mematuhi header Retry-After dari server. Kegagalan deterministik (4xx seperti 401, 404, 422) tidak pernah dicoba ulang. Untuk kunci khusus di antara panggilan SDK terpisah dan batas pemutaran ulang, lihat Idempotensi. Ganti pengaturan idempotensi dan percobaan ulang untuk setiap panggilan:

Contoh kode

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

Kesalahan

Panggilan yang gagal melempar exception. MessageBird\Exception\ApiException mencakup setiap respons kesalahan dari server dan membawa status (status HTTP), type (kategori umum), dan errorCode (kode E##### yang stabil). Kegagalan transport yang menghabiskan anggaran coba lagi melempar MessageBird\Exception\ConnectionException karena tidak ada respons HTTP. Keduanya meng-extend MessageBird\Exception\BirdException, jadi tangkap itu untuk menangani keduanya.

Contoh kode

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

Paginasi

Method list mengembalikan Core\Page yang lazy; mengiterasinya dengan foreach melakukan paginasi otomatis melalui cursor, mengambil halaman sesuai kebutuhan:

Contoh kode

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

Untuk kontrol cursor manual, fetch() mengembalikan satu halaman: data ditambah nextCursor maju, yang Anda berikan kembali sebagai starting_after untuk melanjutkan:

Contoh kode

$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

Escape hatch

Endpoint yang belum tersedia di typed surface dapat diakses melalui $bird->get / post / put / patch / delete, dengan autentikasi, coba lagi, idempotensi, dan penanganan base-URL yang sama:

Contoh kode

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

Temukan path-nya di referensi API.

Webhook

Verifikasi tanda tangan Standard Webhooks dari webhook yang diterima dan dapatkan event yang sudah di-decode. Atur signing secret pada klien (atau berikan per panggilan), dan berikan body request mentah: tanda tangan dihitung dari byte mentah, jadi melakukan parsing sebelum verifikasi adalah bug webhook yang umum terjadi.

Contoh kode

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

Langkah selanjutnya

Quickstart email PHP: pengiriman menyeluruh yang dapat dijalankan.
Konsep SDK: model coba lagi, paginasi, dan region yang digunakan bersama di seluruh SDK.
Referensi API: setiap operasi, dengan contoh PHP.

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Dapatkan ringkasan implementasi

Sumber daya terkait