Download the PHP package tamkeenlms/mobily-sms-api without Composer
On this page you can find all versions of the php package tamkeenlms/mobily-sms-api. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download tamkeenlms/mobily-sms-api
More information about tamkeenlms/mobily-sms-api
Files in tamkeenlms/mobily-sms-api
Package mobily-sms-api
Short Description A non-official PHP client for Mobily's SMS service API
License MIT
Informations about the package mobily-sms-api
About
Mobily.ws is the number one provider for SMS services in the gulf region, but many of their APIs are outdated and badly designed. This is a non-official rewrite of their PHP API client, you will find it more flexible and up-to-date.
Installation
You simply need to require it through Composer:
How it works
You start by defining an API "Client", you can define multible API clients and chose with every request the client through which it will be made. Here's an example:
A new MobilyAPI\Client accepts the following arguaments:
- username: Your account username
- password: The account password
- paramDefault:
- "sender": The default "sender" name for the SMSs.
- "domainName": The application/website domain name through which you use the API. This is automatically filled with the host name.
- "applicationType": This is fixed to "68" (I don't know what it's or what it does, but you are required to send it!)
- "lang": This too is fixed, to "3", which - as it turned out - represents that the encoding used in the requests is UTF-8.
- setup
- "base_uri": The API base uri. You don't need to change this.
- "request_time_out": The time out for the requests, in seconds
- "verify_ssl_certificate": (Boolean) Whether to omit the SSL certificate verification or not. it's false by default
Here is an example:
Requests
Through a Client
you can make an API request
. Of course the request you make will affect the account you chosen for the client through which you made the request. Here is an example for a request that checks the serivce/sending status:
Mobilys's API has a specific number of functions, each function is represented in this library as a request
. Each request has its own class, that you can call directly. So, instead of calling a request through a client
you can create a new request and pass it a client. Here's how:
Each request has its own set of methods that are specific to it. Here is an example:
Each request you make has these methods:
- send(): Which sends the request to the service API.
- object(): Returns the request object, which is an instance of Guzzle HTTP Request
- getClient(): Returns the
Client
which you made the request through - getParams(): Returns an array of the params you passed along with the request
- getResponse(): Returns the response of the request, which is an instance of
Response
- successful(): (Boolean) Tells you if the request to the service API was successful or not.
- failed(): (Boolean)
BTW, you could pull this off in a one-liner, like so:
Responses
Each request
you make returns an instance of the Response
class, which offers the following:
- object(): Which is a Guzzle HTTP Response instance.
- raw(): Returns the response raw body of the request.
- result(): Returns the request result. What is that? well, each request returns a numerical code that represents the result of the request. To get the this numerical value you can use
raw()
but withresult()
you will get a code, like: "connection_failed", "message_sent", "not_enough_credit" .. etc. Each request has its own set or response codes, these code can be found inside the request class.
Example:
Checking service status
Sending a new SMS
Sending a new SMS via this client is done through the Requests\SendSMS
request class:
And here are the args it takes:
- client: The
Client
instance, through which you want to send the SMS - numbers: (Array) The receipient numbers. The original API docs dictates that each number should be in the global format, and with out 00 or + at the beginning.
- message: The message you want to send, UTF-8 encoded.
- time: [optional] Use in case you wanted to schedule this message to be sent later. Here you should provide a valid date/time/datetime format of the time/date you want the message scheduled in. You can also pass a Carbon instance (example below).
- variableSets: [optional] You can use this to send the message to multiple receipients with different values for each receipient. Meaning that the message will become like a template, and each receipient has his/her specific values/information that will be embeded in the associated message (example below).
- messageId: [optional] A unique id for the message. You really need to go back to the original docs of the official API and try to understand what this does. But in general it locks sending the same message to the same number within the same hour. The library will automatically pass a unique id if this argument is omitted.
- sender: [optional] That in case you wanted a different "sender" name for this message, else the default sender will be used.
- deletionKey: [optional] Canceling/deleting a schedule message requires the "deleteKey" for this message, this is where you pass this key. By default the message id will be used here too.
The Requests\SendSMS
class has these methods:
- sent(): (Boolean) Tells if the message was sent and delieverd successfully.
- timeTillSending(): (DateInterval) If the message is scheduled to be sent later this method returns the time difference between now and the time in which it will be send.
- getMessageId(): Returns the message id, the one you picked, or of course the one the library generated for you.
- getDeletionKey(): Returns the message deletion key.
- cancel(): Use this method to cancel a schedule message
Here are the examples:
Schedule for later:
You might want to check Carbon, it's pure awesome.
You can cancel a scheduled new message like this:
Sending a template message:
Deleting a scheduled message
To delete a schedule message you need the message deletion key
If you send a message through Requests\SendSMS
you can get this message deletion key back using getDeletionKey()
. Example:
Retrieving your balance
Hope you find this useful, and please feel free to contact us any time with any questions. Good luck