---
title: "PHP SDK"
description: "Instal dan konfigurasi messagebird/sdk, kirim permintaan pertama Anda, dan pelajari model coba lagi, idempotensi, dan kesalahan pada klien."
canonical: "https://bird.com/id-id/dokumentasi/sdks/php"
---

# 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](https://www.php-fig.org/psr/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](/docs/get-started/quickstarts/php/email).

## Instal

```bash
composer require messagebird/sdk
```

Paket ini diterbitkan sebagai [`messagebird/sdk` di Packagist](https://packagist.org/packages/messagebird/sdk).

## Membuat klien

```php
$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](/docs/sdks/concepts#region-inference) 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

```php
$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](/docs/get-started/quickstarts/php/email).

## 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](/docs/sdks/typescript), [Go](/docs/sdks/go), dan [Python](/docs/sdks/python) berbagi arsitektur ini; lihat [konsep SDK](/docs/sdks/concepts).

## 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](/docs/guides/idempotency). Ganti pengaturan idempotensi dan percobaan ulang untuk setiap panggilan:

```php
$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.

```php
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:

```php
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:

```php
$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:

```php
// 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](/docs/api).

## Webhook

Verifikasi tanda tangan [Standard Webhooks](https://www.standardwebhooks.com/) 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.

```php
// 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](/docs/get-started/quickstarts/php/email): pengiriman menyeluruh yang dapat dijalankan.
- [Konsep SDK](/docs/sdks/concepts): model coba lagi, paginasi, dan region yang digunakan bersama di seluruh SDK.
- [Referensi API](/docs/api): setiap operasi, dengan contoh PHP.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)