PHP SDK

messagebird/sdk Bird API के लिए आधिकारिक PHP SDK है: एक generated wire layer के ऊपर typed, hand-written surface। यह PHP 8.2+ को लक्षित करता है और synchronous है; HTTP आपके पास पहले से मौजूद किसी भी PSR-18 क्लाइंट (Guzzle, Symfony HttpClient, …) के माध्यम से जाता है, जो स्वचालित रूप से detect होता है। यह पेज क्लाइंट को कवर करता है; ईमेल end to end भेजने के लिए PHP email quickstart से शुरू करें।

इंस्टॉल करें

composer require messagebird/sdk

यह पैकेज Packagist पर messagebird/sdk के रूप में प्रकाशित है।

क्लाइंट बनाएँ

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

केवल API key आवश्यक है। region, key के bk_{region}_ prefix से अनुमानित होता है (bk_eu1_… key https://eu1.platform.bird.com पर रूट होती है), इसलिए अधिकांश क्लाइंट केवल key से बनाए जाते हैं; नियमों के लिए region inference देखें। baseUrl region को पूरी तरह ओवरराइड करता है (local या self-hosted)। यहाँ सेट किए गए channel defaults (उदाहरण के लिए email: new EmailDefaults(from: "hello@acme.com")) उस फ़ील्ड को हर send पर वैकल्पिक बना देते हैं, और webhookSecret वह secret है जिससे $bird->webhooks->unwrap() सत्यापन करता है। PSR-18 क्लाइंट पर per-request timeout कॉन्फ़िगर करें जो आप Bird को पास करते हैं। PSR-18 में कोई portable timeout नहीं है, इसलिए transport इस सेटिंग का मालिक है।

पहला कॉल

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

कॉल सीधे API result लौटाता है: यहाँ एक email message अपनी em_* id के साथ। चलाने योग्य walkthrough के लिए PHP quickstart का पालन करें।

दो-लेयर डिज़ाइन

SDK generated और hand-owned layers को जोड़ता है। MessageBird\Wire के अंतर्गत wire types jane-php के माध्यम से Bird की OpenAPI specification से आते हैं, जिससे request और response shapes contract-accurate रहते हैं। Hand-written layer $bird->email->send(...), retries, idempotency, pagination, errors और webhook verification प्रदान करता है। Wire fields snake_case में verbatim पास होते हैं, जैसे category और created_at। केवल SDK-defined identifiers, जिनमें method और option names जैसे idempotencyKey शामिल हैं, camelCase का उपयोग करते हैं। TypeScript, Go और Python SDK यही architecture साझा करते हैं; SDK concepts देखें।

स्वचालित idempotency और retries

हर बदलाव करने वाले ऑपरेशन (POST, PUT, PATCH, DELETE) को अपने-आप बना Idempotency-Key हेडर मिलता है। हर बार फिर से प्रयास करते समय उसी कुंजी का उपयोग होता है, ताकि मेल खाने वाले अनुरोध रखी गई प्रतिक्रिया दोबारा पा सकें। फिर से प्रयास करना डिफ़ॉल्ट रूप से चालू है (maxRetries: 2): क्लाइंट अस्थायी विफलताओं (429, 501 को छोड़कर 5xx और PSR-18 ट्रांसपोर्ट त्रुटियाँ) पर सर्वर के Retry-After हेडर का पालन करते हुए, कुछ यादृच्छिक अंतर के साथ घातीय रूप से बढ़ते प्रतीक्षा समय के बाद फिर से प्रयास करता है। निश्चित विफलताओं (401, 404, 422 जैसे 4xx) पर फिर से प्रयास नहीं किया जाता। अलग-अलग SDK कॉल में कस्टम कुंजियों और प्रतिक्रिया दोबारा लौटाने की सीमाओं के लिए इडेम्पोटेंसी देखें। हर कॉल के लिए इडेम्पोटेंसी और फिर से प्रयास करने की सेटिंग बदलें:

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

त्रुटियाँ

विफल कॉल throw करता है। MessageBird\Exception\ApiException सर्वर से हर त्रुटि प्रतिक्रिया को कवर करता है और status (HTTP status), type (मोटी श्रेणी), और errorCode (स्थिर E##### code) रखता है। Transport failure जो retry बजट समाप्त कर दे, इसके बजाय MessageBird\Exception\ConnectionException throw करती है क्योंकि कोई HTTP response मौजूद नहीं है। दोनों MessageBird\Exception\BirdException को extend करते हैं, इसलिए दोनों को handle करने के लिए उसे catch करें।

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

List methods एक lazy Core\Page लौटाते हैं; foreach के साथ iterate करने पर यह cursors पर auto-paginate करता है और माँग पर pages fetch करता है:

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

Manual cursor control के लिए, fetch() एक single page लौटाता है: उसके data और forward nextCursor, जिसे आप आगे बढ़ने के लिए starting_after के रूप में वापस पास करते हैं:

$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

Typed surface पर अभी उपलब्ध न होने वाले endpoints $bird->get / post / put / patch / delete के माध्यम से उपलब्ध हैं, उसी auth, retries, idempotency और base-URL handling के साथ:

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

Paths API reference में खोजें।

Webhooks

डिलीवर हुए webhook के Standard Webhooks signature को verify करें और decoded event प्राप्त करें। Signing secret क्लाइंट पर सेट करें (या per call पास करें), और raw request body पास करें: signature raw bytes पर होता है, इसलिए verify करने से पहले parse करना webhook का सबसे आम bug है।

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

अगले कदम

• PHP email quickstart: चलाने योग्य end-to-end send।
• SDK concepts: SDKs में साझा retry, pagination और region मॉडल।
• API reference: हर operation, PHP उदाहरणों के साथ।