PHP SDK

messagebird/sdk, Bird API के लिए आधिकारिक PHP SDK है: जनरेट की गई वायर परत के ऊपर हाथ से लिखी गई, टाइप की हुई सतह। यह PHP 8.2+ के लिए है और सिंक्रोनस है; HTTP आपके पास पहले से मौजूद किसी भी PSR-18 क्लाइंट (Guzzle, Symfony HttpClient, …) से होकर जाता है, जिसे अपने आप खोज लिया जाता है। यह पेज केवल क्लाइंट के बारे में है; शुरू से अंत तक ईमेल भेजने के लिए PHP ईमेल क्विकस्टार्ट से शुरू करें।

इंस्टॉल करें

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 कुंजी आवश्यक है। क्षेत्र कुंजी के bk_{region}_ प्रीफ़िक्स से तय होता है (bk_eu1_… कुंजी https://eu1.platform.bird.com पर जाती है), इसलिए अधिकांश क्लाइंट केवल कुंजी से बनाए जाते हैं; नियमों के लिए क्षेत्र का अनुमान देखें। baseUrl क्षेत्र को पूरी तरह बदल देता है (लोकल या सेल्फ़-होस्टेड)। यहाँ सेट किए गए चैनल डिफ़ॉल्ट (जैसे email: new EmailDefaults(from: "hello@acme.com")) उस फ़ील्ड को हर भेजने में वैकल्पिक बना देते हैं, और webhookSecret वह सीक्रेट है जिससे $bird->webhooks->unwrap() सत्यापन करता है। प्रति-अनुरोध टाइमआउट उस PSR-18 क्लाइंट पर कॉन्फ़िगर करें जिसे आप Bird को देते हैं। PSR-18 में कोई पोर्टेबल टाइमआउट नहीं है, इसलिए यह सेटिंग ट्रांसपोर्ट के पास रहती है।

पहली कॉल

$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 परिणाम लौटाती है: यहाँ अपनी em_* id के साथ एक ईमेल संदेश। चलाकर देखने योग्य उदाहरण के लिए PHP क्विकस्टार्ट देखें।

दो-परत वाला डिज़ाइन

SDK जनरेट की गई और हाथ से लिखी गई परतों को जोड़ता है। MessageBird\Wire के अंतर्गत वायर टाइप jane-php के ज़रिए Bird के OpenAPI विनिर्देश से बनते हैं, जिससे अनुरोध और प्रतिक्रिया के ढाँचे अनुबंध के अनुसार सटीक रहते हैं। हाथ से लिखी परत $bird->email->send(...), फिर से प्रयास, आइडेम्पोटेंसी, पेजिनेशन, त्रुटियाँ और वेबहुक सत्यापन देती है। वायर फ़ील्ड snake_case में बिना बदलाव के आते हैं, जैसे category और created_at। केवल SDK द्वारा परिभाषित पहचानकर्ता, जिनमें idempotencyKey जैसे मेथड और विकल्प नाम शामिल हैं, camelCase का उपयोग करते हैं। TypeScript, Go और Python SDK भी यही आर्किटेक्चर अपनाते हैं; SDK अवधारणाएँ देखें।

स्वचालित आइडेम्पोटेंसी और फिर से प्रयास

हर बदलाव वाले अनुरोध (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),
);

त्रुटियाँ

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

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

पेजिनेशन

सूची वाले मेथड एक लेज़ी Core\Page लौटाते हैं; foreach से उस पर इटरेट करने पर वह कर्सर के पार अपने-आप पेजिनेट करता है और ज़रूरत पड़ने पर पेज लाता है:

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

कर्सर को खुद नियंत्रित करने के लिए fetch() एक ही पेज लौटाता है: उसका data और आगे का 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

वैकल्पिक रास्ता

जो एंडपॉइंट अभी टाइप्ड सतह पर नहीं हैं, उन तक $bird->get / post / put / patch / delete से पहुँचा जा सकता है, और इनमें भी वही ऑथेंटिकेशन, फिर से प्रयास, आइडेम्पोटेंसी और बेस 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',
]);

पाथ API संदर्भ में देखें।

वेबहुक

प्राप्त वेबहुक के Standard Webhooks सिग्नेचर को सत्यापित करें और डिकोड किया गया इवेंट पाएँ। साइनिंग सीक्रेट क्लाइंट पर सेट करें (या हर कॉल में दें), और अनुरोध की मूल बॉडी ही भेजें: सिग्नेचर मूल बाइट्स पर बनता है, इसलिए सत्यापन से पहले पार्स करने पर सिग्नेचर सत्यापन विफल हो जाता है।

// 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 ईमेल क्विकस्टार्ट: शुरू से अंत तक ईमेल भेजने का चलाने योग्य उदाहरण।
• SDK अवधारणाएँ: सभी SDK में साझा फिर से प्रयास, पेजिनेशन और क्षेत्र का मॉडल।
• API संदर्भ: PHP उदाहरणों के साथ हर ऑपरेशन।