## Composer

A forma mais fácil de instalar [bulkgate/php-sdk](https://packagist.org/packages/bulkgate/php-sdk) num projeto é utilizar o [Composer](https://getcomposer.org/) através da linha de comandos.

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


Se já tiver o pacote instalado, basta incluir o 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;
```


Para enviar mensagens, precisa de uma instância da classe `BulkGate\Sdk\MessageSender`, que depende de uma instância da classe `BulkGate\Sdk\Connection\Connection`. Veja [como obter os dados de acesso à API](https://www.bulkgate.com/pt/documentacao/administracao-da-api/administracao-de-apis/).

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

Nesta altura, está pronto para enviar uma mensagem.

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

O método `send()` envia a mensagem `$message`.

## O resultado do envio

O método `send()` devolve a mesma mensagem com o estado preenchido. O resultado
lê-se a partir das propriedades públicas:

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

$message->status;     // 'accepted', 'sent', 'scheduled' ou 'error'
$message->message_id; // ID da mensagem
$message->part_id;    // IDs das partes individuais da mensagem
$message->error;      // descrição do erro, caso contrário null
```

Numa mensagem em massa, o estado é preenchido para cada mensagem separadamente —
percorra-a com um ciclo `foreach`.

## Tratamento de erros

O envio pode terminar com uma exceção. Todas elas estendem
`BulkGate\Sdk\SdkException`:

| Exceção | Quando ocorre |
|:--|:--|
| `ConnectionException` | Não foi possível contactar a API |
| `ApiException` | A API devolveu um erro (por exemplo, credenciais inválidas) |
| `SenderException` | Foi passado ao sender um tipo de mensagem desconhecido |
| `InvalidStateException` | Um valor inválido — por exemplo, um código ISO de país ou uma unidade do agendador |
| `ChannelException` | Um erro na configuração dos canais de uma mensagem multicanal |

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

## Configuração opcional

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

Se pretender utilizar números de telefone nacionais, tem de definir o país predefinido.
```php
$sender->setDefaultCountry('sk');
```

Pode adicionar [configuradores](https://www.bulkgate.com/pt/documentacao/php-sdk/php-sdk-configuradores/2.0/) ao sender.

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

Para o agendamento, pode adicionar uma instância de `BulkGate\Sdk\Scheduler\Scheduler`.

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