# PHP library

**Overview**

Use Clickatell’s PHP library with our HTTP or REST messaging APIs to interact with the Clickatell SMS Gateway.

[Get PHP library](https://github.com/clickatell/clickatell-php)

\
**When to use this**

Used by web-based clients to send SMS alerts and notifications. After signing up, use this PHP library to include in your project.

\
**Installation**

This library uses [composer](https://getcomposer.org/) and can be acquired using the following in your composer.json file.

| `{    "require": {        "arcturial/clickatell": "*"    }}` |
| ------------------------------------------------------------ |

 

**Usage**

The library currently supports the `ClickatellHttp` and `ClickatellRest` adapters.

\
**HTTP API**

| `use` `Clickatell\Api\ClickatellHttp;` `$clickatell` `= new` `ClickatellHttp($username, $password, $apiID);$response` `= $clickatell->sendMessage(array(1111111111), "My Message");` `foreach` `($response` `as` `$message) {    echo` `$message->id;` `// Message response fields:    // $message->id    // $message->destination    // $message->error    // $message->errorCode` `}` |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

 

**REST API**

| `use` `Clickatell\Api\ClickatellRest;` `$clickatell` `= new` `ClickatellRest($token);$response` `= $clickatell->sendMessage(array(1111111111), "My Message");` `foreach` `($response` `as` `$message) {    echo` `$message->id;` `// Message response fields:    // $message->id    // $message->destination    // $message->error    // $message->errorCode` `}` |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

 

**Sending to multiple numbers**

The `sendMessage` call `to` parameter can take an array of numbers. If you specify only a single number e.g.:

| `$clickatell->sendMessage(1111111111, "Message")` |
| ------------------------------------------------- |

the library will automatically convert it to an array for your convenience.

 

**Supported API calls**

The available calls are defined in the `Clickatell\TransportInterface` interface.

| `public` `function` `sendMessage($to, $message, $extra` `= array());` `public` `function` `getBalance();` `public` `function` `stopMessage($apiMsgId);` `public` `function` `queryMessage($apiMsgId);` `public` `function` `routeCoverage($msisdn);` `public` `function` `getMessageCharge($apiMsgId);` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

 

**Events**

The library comes with a `ClickatellEvent` class that is a wrapper for any of the other transports. This class can assist you with debugging or logging API interactions.

This class uses the [Proxy Pattern](https://en.wikipedia.org/wiki/Proxy_pattern).

| `<?php` `use` `Clickatell\Api\ClickatellHttp;use` `Clickatell\ClickatellEvent;use` `Clickatellvent;` `$clickatell` `= new` `ClickatellHttp($username, $password, $apiID);$event` `= new` `ClickatellEvent($clickatell);` `$event->onRequest(function` `($event, $args) {` `var_dump($event);    var_dump($args->to);    var_dump($args->message);    var_dump($args->extra);` `// The parameters in the event object depend on the type of event.    // The event constants are available in the Clickatellvent class.` `});` `$event->onResponse(function` `($event, $obj) {` `var_dump($event);var_dump($obj);` `// The $obj variable is the same as the response you would get back. So// in the case of sendMessage it will be an array of message responses.` `});` `$event->sendMessage(array(1111111111), "My Message");` `?>` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### &#x20;

**Dealing with extra parameters in sendMessage**

For usability purposes the `sendMessage` call focuses on the recipients and the content. In order to specify any of the additional parameters defined in the Clickatell document, you can use the `extra` parameter and pass them as an array.

\
**Callbacks**

You can listen to Clickatell callbacks by using the `Callback::parseCallback();` function. It’s a helper function to make sure the required parameters are included in the `$_GET` array.

Parameters: *apiMsgId, cliMsgId, to, timestamp, from, status, charge*

***Example:***

| `use` `Clickatell\Callback;` `Callback::parseCallback(function` `($values) {    // var_dump($values);    // Contains: apiMsgId, cliMsgId, to, timestamp, from, status, charge});` `?>` |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### &#x20;

**OTP/Two-Factor Authentication**

The library has built-in support for sending OTPs (One Time Pins) to verify the identity of a user. This is helpful as a second step during authentication or to validate that the person you are interacting with is a real entity.

| `use` `Clickatell\Otp\SessionStorage;use` `Clickatell\Otp\ClickatellOtp;use` `Clickatell\Api\Rest;` `// Define the OTP storage mechanism. Passing "true" means// a new session will forcibly started.$storage` `= new` `SessionStorage(true);$api` `= new` `Rest([token]);` `$otp` `= new` `ClickatellOtp($api, $storage);` `$otp->setMessage("My custom OTP message. OTP here %s"); // The %s will be replaced with the token.` `$otp->sendPin([number]); // Passing a second argument will assign a unique reference to the token.` `...` `// If you passed a second argument while sending the pin, you must now pass it as a third argument.// The token is the pin you received via SMS. This step is usually done on a form submit.` `$return` `= $otp->verifyPin([number], [token]);` `// $return = true OR false` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### &#x20;

**Symfony Bundle**

In order to start using the bundle, you first need to register it within your `AppKernel.php`

| `class` `AppKernel extends` `Kernel{    public` `function` `registerBundles()    {        $bundles` `= array(            ...            new` `Clickatell\Symfony\ClickatellBundle()        );` `return` `$bundles;    }}` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

&#x20;

You also need to specify your Clickatell credentials in your application config. In this example, [YAML](http://yaml.org/) is used.

| `clickatell:    class:` `Clickatell\Api\ClickatellHttp    arguments:` `[` `"username",` `"password",` `"api_id"` `]` |
| -------------------------------------------------------------------------------------------------------------------- |

&#x20;

**The ‘class’ parameter**

The class parameter can be any class that inherits from `Clickatell\Clickatell`. The default value for this is `Clickatell\Api\ClickatellHttp.`

\
**The ‘arguments’ parameter**

This parameter will be the constructor arguments for your class. What you specify here will depend on what your class takes as constructor arguments.

* The `Clickatell\Api\ClickatellRest` class takes one argument – your API token (issued by Clickatell)
* The `Clickatell\Api\ClickatellHttp` class takes three arguments – your username, password and API ID (issued by Clickatell)

\
**The bundle usage**

Once you have configured the component, you can utilize it in your controllers as shown below:&#x20;

| `class` `DefaultController extends` `Controller{    public` `function` `indexAction()    {        ...` `$clickatell` `= $this->get('clickatell');        $response` `= $clickatell->sendMessage(["number", "number2"], "My Text Message");` `...    }}` |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

&#x20;

You can see our other libraries and more documentation at the [Clickatell APIs and Libraries Project](http://clickatell.github.io/).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.clickatell.com/developers-api-reference/developers-archive/bulk-sms-scripts/php-library.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.