gatewayapi php
1.0.0
Perpustakaan ini akan memungkinkan Anda untuk mengintegrasikan API Gatewayapi.com dalam proyek Anda menggunakan PHP7 modern dan struktur OOP. Untuk deskripsi lengkap API mereka, kode kesalahan dan sebagainya, lihat: https://gatewayapi.com/docs.
Anda memerlukan akun aktif di https://www.gatewayapi.com untuk menggunakan perpustakaan ini. Setelah Anda memilikinya, Anda perlu menghasilkan kunci API Key/Secret di bawah API -> Kunci API .
Untuk memasukkan ini dalam proyek Anda, instal menggunakannya.
Perpustakaan ini membutuhkan PHP> = 7.1 dan berfungsi pada 8.0, 8.1 dan 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 ();
}
} Anda dapat membatalkan SMS yang dijadwalkan berdasarkan ID yang dikembalikan saat mengirim. Karena metode ini membuat kumpulan permintaan (1 per ID pesan) tidak melempar pengecualian tetapi mengembalikan array CancelResult . Masing -masing berisi status dan (jika gagal) pengecualian dari permintaan.
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 ();
}
} Anda dapat dengan mudah menguraikan webhooks yang dikirim dari Gatewayapi ke server Anda menggunakan kelas Webhook . Ini menggunakan header JWT untuk memastikan bahwa webhook belum dirusak dan sebenarnya berasal dari sumber tepercaya.
Untuk mengatur webhook, buka API -> kait web -> istirahat . Tentukan rahasia JWT di bawah otentikasi setelah Anda membuat webhook.
Dua jenis webhook dapat dikirim; pemberitahuan status pengiriman dan pesan yang masuk (lalu lintas MO). Keduanya diuraikan oleh Webhook dan dikembalikan sebagai kelas yang sesuai. Untuk membaca pesan yang masuk, Anda harus berlangganan kata kunci atau nomor berdasarkan langganan -> kata kunci / angka dan menetapkan kata kunci atau nomor ke 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 dan Recipient dikodekan ke dalam JSON yang sebenarnya dikirim ke API. Jika Anda memasukkan output ini ke dalam antrian, atau hal serupa, dan menginginkannya kembali sebagai objek PHP nanti, Anda dapat menggunakan metode ini untuk melakukannya.
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 (); Jika Anda ingin menjalankan tes unit yang tidak memerlukan kredensial, cukup jalankan vendor/bin/phpunit dari akar proyek.
Jika Anda ingin menguji bagian -bagian yang berinteraksi dengan API, Anda harus memberikan kredensial di GatewayAPIHandlerTest.php dan jalankan perintah di atas. Perhatikan bahwa ini mengirimkan SMS langsung dan akan dikenakan biaya 1 SMS dalam kredit per eksekusi.
Anda dapat menghubungi saya di [email protected].
Gunakan perpustakaan ini dengan risiko Anda sendiri. PRS dipersilakan :)
