---
title: "PHP SDK"
description: "Installez et configurez messagebird/sdk, envoyez votre première requête, et découvrez le modèle de réessai, d'idempotence et d'erreur du client."
canonical: "https://bird.com/fr-ch/documentation/sdks/php"
---

# PHP SDK

`messagebird/sdk` est le SDK PHP officiel pour le API Bird : une surface typée, écrite à la main, au-dessus d'une couche réseau générée. Il cible PHP 8.2+ et est synchrone ; HTTP passe par n'importe quel client [PSR-18](https://www.php-fig.org/psr/psr-18/) que vous utilisez déjà (Guzzle, Symfony HttpClient, …), découvert automatiquement. Cette page couvre le client lui-même ; pour envoyer un e-mail de bout en bout, commencez par le [quickstart e-mail PHP](/docs/get-started/quickstarts/php/email).

## Installation

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

Le package est publié sous le nom [`messagebird/sdk` sur Packagist](https://packagist.org/packages/messagebird/sdk).

## Construire un client

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

Seule la clé API est requise. La région est déduite du préfixe `bk_{region}_` de la clé (une clé `bk_eu1_…` est dirigée vers `https://eu1.platform.bird.com`), donc la plupart des clients sont construits avec la clé seule ; consultez [l'inférence de région](/docs/sdks/concepts#region-inference) pour les règles. `baseUrl` remplace entièrement la région (local ou auto-hébergé). Les valeurs par défaut de canal définies ici (par exemple `email: new EmailDefaults(from: "hello@acme.com")`) rendent ce champ optionnel à chaque envoi, et `webhookSecret` est le secret avec lequel `$bird->webhooks->unwrap()` vérifie. Configurez un timeout par requête sur le client PSR-18 que vous passez à `Bird`. PSR-18 n'a pas de timeout portable, donc c'est le transport qui gère ce paramètre.

## Premier appel

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

L'appel renvoie directement le résultat API : ici un message e-mail avec son `em_*` id. Pour un guide exécutable, suivez le [quickstart PHP](/docs/get-started/quickstarts/php/email).

## Conception à deux couches

Le SDK combine des couches générées et écrites à la main. Les types réseau sous `MessageBird\Wire` proviennent de la spécification OpenAPI de Bird via jane-php, garantissant la conformité des structures de requête et de réponse au contrat. La couche écrite à la main fournit `$bird->email->send(...)`, les réessais, l'idempotence, la pagination, les erreurs et la vérification des webhooks. Les champs réseau passent tels quels dans `snake_case`, comme `category` et `created_at`. Seuls les identifiants définis par SDK, y compris les noms de méthodes et d'options comme `idempotencyKey`, utilisent `camelCase`. Les SDK [TypeScript](/docs/sdks/typescript), [Go](/docs/sdks/go) et [Python](/docs/sdks/python) partagent cette architecture ; consultez les [concepts SDK](/docs/sdks/concepts).

## Idempotence et réessais automatiques

Chaque mutation (POST, PUT, PATCH, DELETE) reçoit un en-tête `Idempotency-Key` généré automatiquement. Cette même clé est réutilisée à chaque nouvelle tentative afin que les requêtes identiques puissent restituer la réponse conservée. Les nouvelles tentatives sont activées par défaut (`maxRetries: 2`) : le client réessaie les échecs transitoires (429, 5xx sauf 501 et erreurs de transport PSR-18) avec un délai exponentiel et une variation aléatoire, en respectant l’en-tête `Retry-After` du serveur. Les échecs déterministes (4xx comme 401, 404, 422) ne sont jamais réessayés. Pour les clés personnalisées entre des appels distincts au SDK et les limites de restitution, consultez [Idempotence](/docs/guides/idempotency). Remplacez les paramètres d’idempotence et de nouvelle tentative pour chaque appel :

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

## Erreurs

Un appel échoué lève une exception. `MessageBird\Exception\ApiException` couvre chaque réponse d'erreur du serveur et contient `status` (le statut HTTP), `type` (la catégorie générale) et `errorCode` (le code `E#####` stable). Un échec de transport qui épuise le budget de réessais lève `MessageBird\Exception\ConnectionException` à la place, car aucune réponse HTTP n'existe. Les deux étendent `MessageBird\Exception\BirdException`, donc interceptez celui-ci pour gérer les deux cas.

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

## Pagination

Les méthodes de liste renvoient un `Core\Page` paresseux ; l'itérer avec `foreach` pagine automatiquement à travers les curseurs, en récupérant les pages à la demande :

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

Pour un contrôle manuel du curseur, `fetch()` renvoie une seule page : ses `data` plus le `nextCursor` suivant, que vous repassez comme `starting_after` pour avancer :

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

## Échappatoire

Les endpoints pas encore disponibles sur la surface typée sont accessibles via `$bird->get` / `post` / `put` / `patch` / `delete`, avec la même authentification, les mêmes réessais, la même idempotence et la même gestion de l'URL de base :

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

Retrouvez les chemins dans la [référence API](/docs/api).

## Webhooks

Vérifiez la signature [Standard Webhooks](https://www.standardwebhooks.com/) d'un webhook reçu et obtenez l'événement décodé. Définissez le secret de signature sur le client (ou passez-le par appel), et **transmettez le corps brut de la requête** : la signature porte sur les octets bruts, donc parser avant de vérifier est le bug classique des webhooks.

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

## Étapes suivantes

- [Quickstart e-mail PHP](/docs/get-started/quickstarts/php/email) : un envoi de bout en bout exécutable.
- [Concepts SDK](/docs/sdks/concepts) : le modèle de réessai, de pagination et de région partagé entre les SDK.
- [Référence API](/docs/api) : chaque opération, avec des exemples 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)