## Composer

The easiest way to install [bulkgate/php-sdk](https://packagist.org/packages/bulkgate/php-sdk) into a project is by using [Composer](https://getcomposer.org/) via the command line.

```
composer require bulkgate/php-sdk
```


If you have the package installed just plug in the autoloader.

```php
require_once __DIR__ . '/vendor/autoload.php';
```

```php
use BulkGate\Sdk\Connection\ConnectionStream;
use BulkGate\Sdk\MessageSender;
use BulkGate\Sdk\Scheduler\Simple;
use BulkGate\Sdk\Configurator\ViberConfigurator;
```


In order to send messages, you need an instance of the `BulkGate\Sdk\MessageSender` class that requires instance dependency on the `BulkGate\Sdk\Connection\Connection` class. See [how to get API access data.](https://www.bulkgate.com/en/docs/api-administration-tokens/api-administration/)

```php
$connection = new ConnectionStream(/*application_id: */ 451, /*application_token:*/ 'NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj');
$sender = new MessageSender($connection);
```

At this point, you are ready to send a message.

```php
$message = new Sms('420777777777', 'test message');
$sender->send($message);
```

The `send()` method will send a message `$message`.

## The result of sending

The `send()` method returns the same message with its status filled in. You read
the result from the public properties:

```php
$message = $sender->send(new Sms('420777777777', 'test message'));

$message->status;     // 'accepted', 'sent', 'scheduled' or 'error'
$message->message_id; // message ID
$message->part_id;    // IDs of the individual message parts
$message->error;      // error description, otherwise null
```

For a bulk message the status is filled in for each message separately — walk it
with a `foreach` loop.

## Handling errors

Sending can end with an exception. All of them extend
`BulkGate\Sdk\SdkException`:

| Exception | When it happens |
|:--|:--|
| `ConnectionException` | The API could not be reached |
| `ApiException` | The API returned an error (invalid credentials, for instance) |
| `SenderException` | An unknown message type was passed to the sender |
| `InvalidStateException` | An invalid value — a country ISO code or a scheduler unit, say |
| `ChannelException` | An error in the channel setup of a multichannel message |

```php
try
{
    $sender->send($message);
}
catch (BulkGate\Sdk\SdkException $e)
{
    // log $e->getMessage()
}
```

## Optional configuration

```php
$sender->setTag('your identificator');
```

If you want to use national phone numbers you must set default country.
```php
$sender->setDefaultCountry('sk');
```

You can add [configurators](https://www.bulkgate.com/en/docs/php-sdk/php-sdk-configurators/2.0/) to sender.

```php
$viber_configurator = new ViberConfigurator('Sender');
$sender->addSenderConfigurator($viber_configurator);
```

For scheduling you can add instance of `BulkGate\Sdk\Scheduler\Scheduler`.

```php
$scheduler = new Simple(new DateTime('2022-05-14 20:00:00'));
$sender->setScheduler($scheduler);
```