gatewayapi php
1.0.0
ห้องสมุดนี้จะช่วยให้คุณสามารถรวม API GatewayAPI.com ในโครงการของคุณโดยใช้ PHP7 ที่ทันสมัยและโครงสร้าง OOP สำหรับคำอธิบายทั้งหมดของ API รหัสข้อผิดพลาดและอื่น ๆ ดู: https://gatewayapi.com/docs
คุณต้องมีบัญชีที่ใช้งานได้ที่ https://www.gatewayapi.com เพื่อใช้ห้องสมุดนี้ เมื่อคุณมีสิ่งที่คุณต้องสร้างคีย์ API/คู่ลับภายใต้คีย์ API -> API
หากต้องการรวมสิ่งนี้ไว้ในโครงการของคุณให้ติดตั้งโดยใช้นักแต่งเพลง
ห้องสมุดนี้ต้องการ php> = 7.1 และทำงานบน 8.0, 8.1 และ 8.2
composer require nickdnk/gatewayapi-php
use nickdnk GatewayAPI GatewayAPIHandler ;
use nickdnk GatewayAPI Entities Request Recipient ;
use nickdnk GatewayAPI Entities Request SMSMessage ;
// Pass `true` as the third parameter to use GatewayAPI in EU-only mode.
// This requires an EU account. See https://gatewayapi.com/blog/new-eu-setup-for-gatewayapi-customers/.
$ handler = new GatewayAPIHandler ( ' my_key ' , ' my_secret ' , false );
$ message1 = new SMSMessage (
// The message you want to send. Include any placeholder tag strings.
' Hello, %FIRSTNAME%! Your code is: %CODE%. ' ,
// The name of the sender as seen by the recipient.
// 1-11 ASCII characters, spaces are removed.
' MyService ' ,
// An array containing the recipient(s) you want to send the message
// to. You can also pass an empty array and add recipients later on.
// See the example below the constructor.
[ new Recipient ( 4512345678 , [ ' John ' , ' 23523 ' ])],
// Arbitrary label added to your message(s).
// Pass null if you don't need this.
' customer1 ' ,
// The strings to replace in your message with tag values for each
// recipient. Pass an empty array if you don't use tags in your message.
[ ' %FIRSTNAME% ' , ' %CODE% ' ],
// The UNIX timestamp for when you want your message to be sent.
// Pass null to send immediately. This should *not* be less than
// the current UNIX time. This example sends in 1 hour.
time () + 3600 ,
// The message class to use. Note that prices vary. The secret class
// requires approval by GatewayAPI on your account before you can use
// it, otherwise you will get an error.
SMSMessage:: CLASS_STANDARD
);
// If you prefer a shorter constructor, you can use the default values
// and set your parameters after construction.
$ message2 = new SMSMessage ( ' Hello %NAME%! Your code is: %CODE% ' , ' MyService ' );
$ message2 -> setSendTime ( time () + 3600 );
$ message2 -> setClass (SMSMessage:: CLASS_PREMIUM );
$ message2 -> setUserReference ( ' customer1 ' );
$ message2 -> setTags ([ ' %NAME% ' , ' %CODE% ' ]);
$ message2 -> setCallbackUrl ( ' https://example.com/callback ' );
$ message2 -> addRecipient ( new Recipient ( 4587652222 , [ ' Martha ' , ' 42442 ' ]));
try {
// Note that a single SMSMessage must not contain more than 10,000
// recipients. If you want to send to more than 10,000 you should split
// your recipients into several SMSMessages. You can, however, send
// multiple SMSMessages in a single request.
$ result = $ handler -> deliverMessages (
[
$ message1 ,
$ message2
]
);
// All message IDs returned.
$ result -> getMessageIds ();
// The total cost of this request (all message IDs combined).
$ result -> getTotalCost ();
// Currency you were charged in.
$ result -> getCurrency ();
// The number of messages sent. For a message that's 3 SMSes long
// with 1000 recipients, this will be 3000.
$ totalMessagesSent = $ result -> getTotalSMSCount ();
// Messages sent to UK only.
$ ukMessages = isset ( $ result -> getCountries ()[ ' UK ' ])
? $ result -> getCountries ()[ ' UK ' ]
: 0 ;
} catch ( nickdnk GatewayAPI Exceptions InsufficientFundsException $ e ) {
/**
* Extends GatewayRequestException.
*
* Your account has insufficient funds and you cannot send the
* message(s) before you buy more credits at gatewayapi.com.
*
* The request body can be retried after you top up your balance.
*/
} catch ( nickdnk GatewayAPI Exceptions MessageException $ e ) {
/**
* Extends GatewayRequestException.
*
* This should not happen if you properly use the library and pass
* correct data into the functions, but it indicates that whatever
* you're doing is not allowed by GatewayAPI.
*
* It can happen if you add the same phone number (recipient) twice
* to an SMSMessage or if you don't use the tags function correctly,
* such as not providing a tag value for a recipient within a message
* that has a defined set of tags, or if you provide a tag value as
* an integer.
*
* To add the same phone number twice to one request it must be in
* different SMSMessage objects.
*
* Requests that throw this exception should *not* be retried!
*/
// The error code (may be null)
$ e -> getGatewayAPIErrorCode ();
// Error message, if present.
$ e -> getMessage ();
// Full response.
$ e -> getResponse ()-> getBody ();
} catch ( nickdnk GatewayAPI Exceptions SuccessfulResponseParsingException $ e ) {
/**
* Extends GatewayRequestException.
*
* If you implement automatic retries of failed requests, you should
* check for this exception. It is unlikely to ever occur, but it
* could happen if GatewayAPI changed their API or there was an error
* in the library. This could potentially trigger retries for requests
* that succeeded which would be expensive as well as problematic
* for recipients.
*/
// Error message.
$ e -> getMessage ();
// Full response.
$ e -> getResponse ()-> getBody ();
} catch ( nickdnk GatewayAPI Exceptions UnauthorizedException $ e ) {
/**
* Extends GatewayRequestException.
*
* Something is wrong with your credentials or your IP is
* banned. Make sure you API key and secret are valid or contact
* customer support.
*
* The request body can be retried if you provide different
* credentials (or fix whatever is wrong).
*/
// The error code (may be null)
$ e -> getGatewayAPIErrorCode ();
// Error message, if present.
$ e -> getMessage ();
// Full response.
$ e -> getResponse ()-> getBody ();
} catch ( nickdnk GatewayAPI Exceptions GatewayServerException $ e ) {
/**
* Extends GatewayRequestException.
*
* Something is wrong with GatewayAPI.com. This exception simply
* extends GatewayRequestException but only applies to 500-range
* errors.
*
* The request body can (most likely) be retried.
*/
// The error code (may be null)
$ e -> getGatewayAPIErrorCode ();
// Error message.
$ e -> getMessage ();
// Full response.
$ e -> getResponse ()-> getBody ();
} catch ( nickdnk GatewayAPI Exceptions ConnectionException $ e ) {
/**
* Connection to GatewayAPI failed or timed out. Try again or
* check their server status at https://status.gatewayapi.com/
*
* The request can/should be retried. This library does not
* automatically retry requests that fail for this reason.
*/
// Error message.
$ e -> getMessage ();
} catch ( nickdnk GatewayAPI Exceptions BaseException $ e ) {
/**
* Something else is wrong.
* All exceptions inherit from this one, so you can catch this error
* to handle all errors the same way or implement your own error
* handler based on the error code. Remember to check for nulls.
*
* This exception is abstract, so you can check which class it is
* and go from there.
*/
// Error message.
$ e -> getMessage ();
if ( $ e instanceof nickdnk GatewayAPI Exceptions GatewayServerException) {
// The error code (may be null).
$ e -> getGatewayAPIErrorCode ();
$ response = $ e -> getResponse ();
$ response -> getBody ();
$ response -> getStatusCode ();
}
} คุณสามารถยกเลิก SMS ที่กำหนดตามรหัสที่ส่งคืนเมื่อส่ง เนื่องจากวิธีนี้สร้างกลุ่มของคำขอ (1 ต่อรหัสข้อความ) มันไม่ได้โยนข้อยกเว้น แต่ส่งคืนอาร์เรย์ของ CancelResult แต่ละเหล่านี้มีสถานะและข้อยกเว้น (หากล้มเหลว) ของคำขอ
use nickdnk GatewayAPI Entities CancelResult ;
use nickdnk GatewayAPI GatewayAPIHandler ;
$ handler = new GatewayAPIHandler ( ' my_key ' , ' my_secret ' );
$ results = $ handler -> cancelScheduledMessages ([ 1757284 , 1757288 ]);
foreach ( $ results as $ cancelResult ) {
// The ID of the canceled message is always available.
$ cancelResult -> getMessageId ();
if ( $ cancelResult -> getStatus () === CancelResult:: STATUS_SUCCEEDED ) {
// Success. Obviously.
} elseif ( $ cancelResult -> getStatus () === CancelResult:: STATUS_FAILED ) {
// Get the exception of a failed request.
$ cancelResult -> getException ();
}
} คุณสามารถแยกวิเคราะห์ webhooks ที่ส่งจาก gatewayapi ไปยังเซิร์ฟเวอร์ของคุณได้อย่างง่ายดายโดยใช้คลาส Webhook สิ่งนี้ใช้ส่วนหัวของ JWT เพื่อให้แน่ใจว่า webhook ไม่ได้ถูกดัดแปลงและในความเป็นจริงมาจากแหล่งที่เชื่อถือได้
หากต้องการตั้งค่า webhooks ไปที่ API -> Web Hooks -> REST ระบุความลับของ JWT ภายใต้การรับรองความถูกต้องหลังจากที่คุณได้สร้าง webhook
สามารถส่ง webhooks สองประเภทได้ การแจ้งเตือนสถานะการจัดส่งและข้อความขาเข้า (การรับส่งข้อมูล MO) ทั้งสองถูกแยกวิเคราะห์โดย Webhook และกลับมาเป็นคลาสที่สอดคล้องกัน ในการอ่านข้อความที่เข้ามาคุณต้องสมัครสมาชิกคำหลักหรือหมายเลขภายใต้ การสมัครสมาชิก -> คำหลัก / หมายเลข และกำหนดคำหลักหรือหมายเลขให้กับ webhook
use nickdnk GatewayAPI Entities Webhooks DeliveryStatusWebhook ;
use nickdnk GatewayAPI Entities Webhooks IncomingMessageWebhook ;
use nickdnk GatewayAPI Entities Webhooks Webhook ;
use Psr Http Message RequestInterface ;
use Psr Http Message ResponseInterface ;
/**
* The webhook parser is based on PSR-7 allowing you to pass a $request
* object directly into the class and get a webhook back.
*/
function ( RequestInterface $ request , ResponseInterface $ response ) {
try {
$ webhook = Webhook:: constructFromRequest ( $ request , ' my_jwt_secret ' );
// Determine the type of webhook if you don't already know.
if ( $ webhook instanceof DeliveryStatusWebhook) {
$ webhook -> getPhoneNumber ();
$ webhook -> getStatus ();
} elseif ( $ webhook instanceof IncomingMessageWebhook) {
$ webhook -> getPhoneNumber ();
$ webhook -> getWebhookLabel ();
$ webhook -> getMessageText ();
}
} catch ( nickdnk GatewayAPI Exceptions WebhookException $ exception ) {
// Something is wrong with the webhook or it was not correctly
// signed. Take a look at your configuration.
$ exception -> getMessage ();
}
}
/**
* Or if you don't have a PSR-7 request handy, you can pass the JWT
* directly into this method instead. Note that the JWT contains
* the entire payload, which is duplicated unsigned in the body of the
* request. We don't read the request body at all.
*/
// JWT as a string, read from where-ever:
$ jwt = ' eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ' ;
try {
$ webhook = Webhook:: constructFromJWT ( $ jwt , ' my_jwt_secret ' );
} catch ( nickdnk GatewayAPI Exceptions WebhookException $ exception ) {
$ exception -> getMessage ();
} SMSMessage และ Recipient จะถูกเข้ารหัสลงใน JSON จริงที่ส่งไปยัง API หากคุณใส่เอาต์พุตนี้ลงในคิวหรืออะไรที่คล้ายกันและต้องการให้พวกเขากลับมาเป็นวัตถุ PHP ในภายหลังคุณสามารถใช้วิธีการเหล่านี้เพื่อทำเช่นนั้น
use nickdnk GatewayAPI Entities Request Recipient ;
use nickdnk GatewayAPI Entities Request SMSMessage ;
$ recipient = new Recipient ( 4587652222 , [ ' Martha ' , ' 42442 ' ]);
$ json = json_encode ( $ recipient );
$ recipient = Recipient:: constructFromJSON ( $ json );
$ message = new SMSMessage ( ' Hello %NAME%! Your code is: %CODE% ' , ' MyService ' );
$ message -> setSendTime ( time () + 3600 );
$ message -> setUserReference ( ' reference ' );
$ message -> setTags ([ ' %NAME% ' , ' %CODE% ' ]);
$ message -> addRecipient ( $ recipient );
$ json = json_encode ( $ message );
$ smsMessage = SMSMessage:: constructFromJSON ( $ json );
$ smsMessage -> getMessage ();
$ smsMessage -> getRecipients (); หากคุณต้องการเรียกใช้การทดสอบหน่วยที่ไม่ต้องการข้อมูลรับรองเพียงเรียกใช้ vendor/bin/phpunit จากรูทของโครงการ
หากคุณต้องการทดสอบชิ้นส่วนที่โต้ตอบกับ API คุณต้องให้ข้อมูลรับรองใน GatewayAPIHandlerTest.php และเรียกใช้คำสั่งด้านบน โปรดทราบว่าสิ่งนี้จะส่ง SMS สดและจะเสียค่าใช้จ่าย 1 SMS ในเครดิตต่อการดำเนินการ
คุณสามารถติดต่อฉันได้ที่ [email protected]
ใช้ห้องสมุดนี้ตามความเสี่ยงของคุณเอง ยินดีต้อนรับ PRS :)
