https://github.com/mediaburst/clockwork-php
PHP wrapper for Clockwork SMS from Mediaburst.
https://github.com/mediaburst/clockwork-php
clockwork php sms sms-api sms-messages
Last synced: 6 months ago
JSON representation
PHP wrapper for Clockwork SMS from Mediaburst.
- Host: GitHub
- URL: https://github.com/mediaburst/clockwork-php
- Owner: mediaburst
- License: mit
- Created: 2012-04-30T15:47:59.000Z (almost 14 years ago)
- Default Branch: master
- Last Pushed: 2017-11-30T10:59:54.000Z (about 8 years ago)
- Last Synced: 2025-08-04T22:07:54.627Z (6 months ago)
- Topics: clockwork, php, sms, sms-api, sms-messages
- Language: PHP
- Homepage: http://www.clockworksms.com/
- Size: 50.8 KB
- Stars: 46
- Watchers: 21
- Forks: 41
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: license.txt
Awesome Lists containing this project
README
# Clockwork SMS API Wrapper for PHP
This wrapper lets you interact with Clockwork without the hassle of having to create any XML or make HTTP calls.
## What's Clockwork?
[Clockwork][2] is Mediaburst's SMS API.
### Prerequisites
* A [Clockwork][2] account
## Usage
### Installing with composer
The easiest way to get Clockwork is to use [Composer][4] to automatically download and include it in your project. Setup [Composer][4] and add us to your composer.json
```php
{
"require": {
"mediaburst/clockworksms": "2.0.*"
}
}
```
If you are using your own autoloader we are using the PSR-4 namespacing scheme.
### Including directly
Download the Clockwork library, put it in your project and require the Clockwork class and the ClockworkException classes:
```php
require 'src/Clockwork.php';
require 'src/ClockworkException.php';
```
### Sending a message
```php
$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY ); //Be careful not to post your API Keys to public repositories.
$message = array( 'to' => '441234567891', 'message' => 'This is a test!' );
$result = $clockwork->send( $message );
```
### Sending multiple messages
We recommend you use batch sizes of 500 messages or fewer. By limiting the batch size it prevents any timeouts when sending.
```php
$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY ); //Be careful not to post your API Keys to public repositories.
$messages = array(
array( 'to' => '441234567891', 'message' => 'This is a test!' ),
array( 'to' => '441234567892', 'message' => 'This is a test 2!' )
);
$results = $clockwork->send( $messages );
```
### Handling the response
The responses come back as arrays, these contain the unique Clockwork message ID, whether the message worked (`success`), and the original SMS so you can update your database.
Array
(
[id] => VE_164732148
[success] => 1
[sms] => Array
(
[to] => 441234567891
[message] => This is a test!
)
)
If you send multiple SMS messages in a single send, you'll get back an array of results, one per SMS.
The result will look something like this:
Array
(
[0] => Array
(
[id] => VI_143228951
[success] => 1
[sms] => Array
(
[to] => 441234567891
[message] => This is a test!
)
)
[1] => Array
(
[id] => VI_143228952
[success] => 1
[sms] => Array
(
[to] => 441234567892
[message] => This is a test 2!
)
)
)
If a message fails, the reason for failure will be set in `error_code` and `error_message`.
For example, if you send to invalid phone number "abc":
Array
(
[error_code] => 10
[error_message] => Invalid 'To' Parameter
[success] => 0
[sms] => Array
(
[to] => abc
[message] => This is a test!
)
)
### Checking your balance
Check your available SMS balance:
```php
$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY ); //Be careful not to post your API Keys to public repositories.
$clockwork->checkBalance();
```
This will return:
Array
(
[symbol] => £
[balance] => 351.91
[code] => GBP
[account_type] => PAYG
)
Account Type can be either PAYG or Invoice.
### Handling Errors
The Clockwork wrapper will throw a `ClockworkException` if the entire call failed.
```php
try
{
$clockwork = new mediaburst\ClockworkSMS\Clockwork( 'invalid_key' );
$message = array( 'to' => 'abc', 'message' => 'This is a test!' );
$result = $clockwork->send( $message );
}
catch( mediaburst\ClockworkSMS\ClockworkException $e )
{
print $e->getMessage();
// Invalid API Key
}
```
### Advanced Usage
This class has a few additional features that some users may find useful, if these are not set your account defaults will be used.
### Optional Parameters
See the [Clockwork Documentation](http://www.clockworksms.com/doc/clever-stuff/xml-interface/send-sms/) for full details on these options.
* $from [string]
The from address displayed on a phone when they receive a message
* $long [boolean]
Enable long SMS. A standard text can contain 160 characters, a long SMS supports up to 459.
* $truncate [nullable boolean]
Truncate the message payload if it is too long, if this is set to false, the message will fail if it is too long.
* $invalid_char_action [string]
What to do if the message contains an invalid character. Possible values are
* error - Fail the message
* remove - Remove the invalid characters then send
* replace - Replace some common invalid characters such as replacing curved quotes with straight quotes
* $ssl [boolean, default: true]
Use SSL when making an HTTP request to the Clockwork API
### Setting Options
#### Global Options
Options set on the API object will apply to all SMS messages unless specifically overridden.
In this example both messages will be sent from Clockwork:
```php
$options = array( 'from' => 'Clockwork' );
$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY, $options ); //Be careful not to post your API Keys to public repositories.
$messages = array(
array( 'to' => '441234567891', 'message' => 'This is a test!' ),
array( 'to' => '441234567892', 'message' => 'This is a test 2!' )
);
$results = $clockwork->send( $messages );
```
#### Per-message Options
Set option values individually on each message.
In this example, one message will be from Clockwork and the other from 84433:
```php
$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY, $options ); //Be careful not to post your API Keys to public repositories.
$messages = array(
array( 'to' => '441234567891', 'message' => 'This is a test!', 'from' => 'Clockwork' ),
array( 'to' => '441234567892', 'message' => 'This is a test 2!', 'from' => '84433' )
);
$results = $clockwork->send( $messages );
```
### SSL Errors
Due to the huge variety of PHP setups out there a small proportion of users may get PHP errors when making API calls due to their SSL configuration.
The errors will generally look something like this:
```
Fatal error:
Uncaught exception 'Exception' with message 'HTTP Error calling Clockwork API
HTTP Status: 0
cURL Erorr: SSL certificate problem, verify that the CA cert is OK.
Details: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed'
```
If you're seeing this error there are two fixes available, the first is easy, simply disable SSL on Clockwork calls. Alternatively you can setup your PHP install with the correct root certificates.
#### Disable SSL on Clockwork calls
```php
$options = array( 'ssl' => false );
$clockwork = new mediaburst\ClockworkSMS\Clockwork( $API_KEY, $options ); //Be careful not to post your API Keys to public repositories.
```
#### Setup SSL root certificates on your server
This is much more complicated as it depends on your setup, however there are many guides available online.
Try a search term like "windows php curl root certificates" or "ubuntu update root certificates".
# License
This project is licensed under the MIT open-source license.
A copy of this license can be found in license.txt.
# Contributing
If you have any feedback on this wrapper drop us an email to [hello@clockworksms.com][1].
The project is hosted on GitHub at [https://github.com/mediaburst/clockwork-php][3].
If you would like to contribute a bug fix or improvement please fork the project
and submit a pull request.
[1]: mailto:hello@clockworksms.com
[2]: http://www.clockworksms.com/
[3]: https://github.com/mediaburst/clockwork-php
[4]: https://getcomposer.org/