From 5752f7639e07c730dab6a14891ee01d0ee8d9c41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Pij=C3=A1k?= Date: Tue, 21 Dec 2021 19:23:32 +0100 Subject: [PATCH] documentation --- README.md | 493 +++--------------- docs/bulk.md | 36 +- docs/configurators.md | 12 +- docs/multichannel_message.md | 19 +- docs/number_checker.md | 49 +- docs/schedulers.md | 15 +- docs/sender.md | 79 ++- docs/sms_message.md | 28 +- docs/viber_message.md | 50 +- src/MessageSender.php | 1 - tests/Message/Components/ButtonTest.phpt | 2 +- tests/Message/Components/ImageTest.phpt | 2 +- tests/Message/Components/PhoneNumberTest.phpt | 2 +- tests/Message/Components/SimpleTextTest.phpt | 2 +- tests/Message/Components/SmsSenderTest.phpt | 2 +- 15 files changed, 275 insertions(+), 517 deletions(-) diff --git a/README.md b/README.md index 9e1e36f..840aa76 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,15 @@ BulkGate SMS - PHP SDK ============= -[![Downloads](https://img.shields.io/packagist/dt/bulkgate/sms.svg)](https://packagist.org/packages/bulkgate/sms) -[![Latest Stable Version](https://img.shields.io/github/release/bulkgate/sms.svg)](https://github.com/bulkgate/sms/releases) -[![License](https://img.shields.io/github/license/bulkgate/sms.svg)](https://github.com/BulkGate/sms/blob/master/LICENSE) +[![Downloads](https://img.shields.io/packagist/dt/bulkgate/php-sdk.svg)](https://packagist.org/packages/bulkgate/php-sdk) +[![Latest Stable Version](https://img.shields.io/github/release/bulkgate/php-sdk.svg)](https://github.com/bulkgate/php-sdk/releases) +[![License](https://img.shields.io/github/license/bulkgate/php-sdk.svg)](https://github.com/BulkGate/php-sdk/blob/master/LICENSE) -- [BulkGate portal](https://portal.bulkgate.com/) - [BulkGate](https://www.bulkgate.com/) +- [Helpdesk](https://help.bulkgate.com/) +- [Portal](https://portal.bulkgate.com/) -## Instalation +## Installation 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. @@ -16,450 +17,110 @@ The easiest way to install [bulkgate/php-sdk](https://packagist.org/packages/bul composer require bulkgate/php-sdk ``` +## Quick start -If you have the package installed just plug in the autoloader. +### Nette DI Extension -``` php -require_once __DIR__ . '/vendor/autoload.php'; -``` - -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. - -``` php -$connection = new BulkGate\Sdk\Connection\ConnectionStream('APPLICATION_ID', 'APPLICATION_TOKEN'); - -$sender = new BulkGate\Sdk\MessageSender($connection); -``` - -At this point, you are ready to send a message. +```neon +extensions: + sdk: BulkGate\Sdk\DI\Extension -``` php -$message = new Sms("420603902776", "test_text"); +sdk: + application_id: 0000 + application_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + sender: + tag: 'sdk' # Optional + default_country: cz # Optional + configurator: + sms: # Optional + sender_id: gText + sender_id_value: 'Example' + unicode: true + viber: # Optional + sender: Sender + button: + caption: 'Button Caption' + url: 'https://www.bulkgate.com/' + image: + url: 'https://www.example.com/example.png' + zoom: true + expiration: 3600 # seconds ``` -The `send()` method will send a message `$message`. +```php -## API administration & tokens - -[API administration](https://help.bulkgate.com/docs/en/api-administration.html) - -[API token](https://help.bulkgate.com/docs/en/api-tokens.html) - -## Transactional SMS - -The `BulkGate\Sdk\Message\Sms` class represents the object of the SMS message, which consists of the content of the message and the recipient. - -``` php +use BulkGate\Sdk\Sender; use BulkGate\Sdk\Message\Sms; -``` - -### Recipient - -The class accepts as the first argument a phone number that can be entered by a string: - -``` php -$message = new Sms("420603902776", "test_text"); -``` - -or accepts an instance of the object `BulkGate\Sdk\Message\Component\PhoneNumber`: - -``` php -$message = new Sms(new BulkGate\Sdk\Message\Component\PhoneNumber('777777777', 'cz'), 'test message'); -``` - -To obtain a phone number, you can use the print out the class object `BulkGate\Sdk\Message\Component\PhoneNumber`, which always returns a phone number as a string. - -You can also set phone number and iso separately - -``` php -$phone_number = new PhoneNumber(); -$phone_number->phoneNumber("777777777"); -$phone_number->iso("cz"); -``` - -### Text of the message - -The second parameter is the input of the text of the message. There are also 2 options where the first is to enter text using a `string`, and the other is an instance of the class `component\SimpleText`, or `null`. - -``` php -$phone_number = new PhoneNumber('777777777', 'cz'); -$text = new SimpleText("test ", ["variable" => "message"]); - -$message = new Sms($phone_number, $text); -``` - -Of course, you can define text even after creating an instance of an object using the method `text(string $text, array $variables = [])` - -``` php -$phone_number = new PhoneNumber("603902776", "cz"); - -$message = new Sms($phone_number); - -$message->text("test ", ["variable" => "message"]) -``` - -You can use the `getChannels()` method, to retrieve the array of used channels. - -``` php -/** @var array $channels */ -$channels = $message->getChannels(); -``` - -### Settings - -You can accesss public variable settings to configure [sender_id](https://help.bulkgate.com/docs/en/http-advanced-transactional.html#sender-id-type-sender_id) and unicode -``` php -$sender_id = "gText"; -$sender_id_value = "Test sender"; -$unicode = false; - -$message->settings->configure($sender_id, $sender_id_value, $unicode); -``` - -### JSON Supoort - -The `BulkGate\Sms\Message` object implements the `\JsonSerializable` interface that lets you convert it via the `json_encode()` to JSON format. - -``` php -/** @var BulkGate\Sdk\Message\Sms $message */ -$message = new Sms('420777777777', 'test message'); - -echo json_encode($message); -``` - -The output is: - -``` json +class Sdk { - "primary_channel": "sms", - "phone_number": "777777777", - "country": "cz", - "channels": { - "sms": { - "text": "test_text", - "variables": [], - "sender_id": "gSystem", - "sender_id_value": "", - "unicode": false - } - } -} -``` - -### Convert to string - -``` php -$message = new Sms("420777777777", "test_text"); -echo (string)$message; // to the output -``` - -The output is: - -``` php -420777777777 -``` - -### Fluent interface - -[Fluent interface](https://en.wikipedia.org/wiki/Fluent_interface) is the technique of chaining methods. Every object of this SDK includes fluent interface. + private Sender $sender; -``` php -$phone_number = new PhoneNumber("420777777777"); -$phone_number->phoneNumber("777777777")->iso("cz"); -``` - -## Viber message -The `BulkGate\Sdk\Message\Viber` class represents the object of the Viber message, which consists of the content of the message and the recipient. - -``` php -use BulkGate\Sdk\Message\Viber; -``` - -### Recipient - -The class accepts as the first argument a phone number that can be entered by a string: - -``` php -$message = new Viber("420777777777", "test_text"); -``` - -or accepts an instance of the object `BulkGate\Sdk\Message\Component\PhoneNumber`: - -``` php -$message = new Viber(new BulkGate\Sdk\Message\Component\PhoneNumber('777777777', 'cz'), 'test message'); -``` - -To obtain a phone number, you can use the print out the class object `BulkGate\Sdk\Message\Component\PhoneNumber`, which always returns a phone number as a string. - -You can also set phone number and iso separately - -``` php -$phone_number = new PhoneNumber(); -$phone_number->phoneNumber("777777777"); -$phone_number->iso("cz"); -``` - -### Text of the message - -The second parameter is the input of the text of the message. There are also 2 options where the first is to enter text using a `string`, and the other is an instance of the class `component\SimpleText`, or `null`. - -``` php -$phone_number = new PhoneNumber('777777777', 'cz'); -$text = new SimpleText("test ", ["variable" => "message"]); - -$message = new Viber($phone_number, $text); -``` - -Of course, you can define text even after creating an instance of an object using the method `text(string $text, array $variables = [])` - -``` php -$phone_number = new PhoneNumber("777777777", "cz"); - -$message = new Viber($phone_number); - -$message->text("test ", ["variable" => "message"]) -``` - -You can use the `getChannels()` method, to retrieve the array of used channels. - -``` php -/** @var array $channels */ -$channels = $message->getChannels(); -``` - -### Settings -Third parameter of Viber object is `sender` which is defined as `string`. - -``` php -$message = new Viber("420777777777", "text message", "Sender"); -``` - -Viber's functionality provides an option to use buttons and images in your messages - -``` php -use BulkGate\Sdk\Message\Component\Button - -$button = new Button("Caption", "url"); - -$message = new Viber("420777777777", "text message", "Sender", $button); -``` - -Image input parameters include url of image location and boolean that determines whether the image will be zoomable. - -``` php -use BulkGate\Sdk\Message\Component\Image; - -$image = new Image("image url", false); -``` - - - -### JSON Supoort - -The `BulkGate\Sms\Message` object implements the `\JsonSerializable` interface that lets you convert it via the `json_encode()` to JSON format. - -``` php -/** @var BulkGate\Sdk\Message\Sms $message */ -$message = new Viber('420777777777', 'test message'); - -echo json_encode($message); -``` - -The output is: + public funnction __construct(Sender $sender) + { + $this->sender = $sender; + } + -``` json -{ - "primary_channel": "viber", - "phone_number": "420777777777", - "country": null, - "channels": { - "viber": { - "text": "test_text", - "variables": [], - "sender": null, - "button_caption": "OK", - "button_url": "#", - "image": null, - "image_zoom": false, - "expiration": 10800 + public function sendMessage(string $phone_number, string $text): void + { + $this->sender->send(new Sms($phone_number, $text)); } - } } -``` - -### Convert to string - -``` php -$message = new Viber("420777777777", "test_text"); -echo (string)$message; -``` - -The output is: - -``` php -420777777777 -``` - -### Fluent interface - -[Fluent interface](https://en.wikipedia.org/wiki/Fluent_interface) is the technique of chaining methods. Every object of this SDK includes fluent interface. - -``` php -$phone_number = new PhoneNumber("603902776", "cz"); -$phone_number->phoneNumber("777777777")->iso("cz"); -``` - - -## Multichannel message - -Multichannel allows you to send message via Viber and in case recipient does not own Viber account, SMS message will be send instead. - -``` php -$phone_number = new PhoneNumber("420777777777", "cz"); -$text = new SimpleText("test ", ["variable" => "message"]); -$button = new Button("Caption", "url"); -$image = new Image("image url", false); -$timeout = 5; - -$message = new MultiChannel($phone_number); - -$message->sms($text, "gText", "Sender", false); -$message->viber($text, "Sender", $button, $image, $timeout); - -$this->sender->send($message); -``` - -### Settings - -You can also change the settings of individual channels after the fact - -``` php -$message->configure(Channel::SMS, $sender_id, $sender_id_value, $unicode); -$message->configure(Channel::VIBER, "sender", $button, $image, $timeout); -``` - -### Setting channel - -Based on used settings interface method channel can be used. - -``` php -$settings = new \BulkGate\Sdk\Message\Settings\Viber(new SimpleText("text_message"), "sender", $button, $image, $timeout); - -$message->channel($settings); -``` - -### Setting primary channel - -You can use method `setPrimaryChannel` to set channel priority -``` php -$message->setPrimaryChannel(Channel::VIBER); ``` -### Get channels +### Manual creation -Method `getChannels` can be used to get channels used in message +```php +use BulkGate\Sdk\Connection\ConnectionStream; +use BulkGate\Sdk\MessageSender; +use BulkGate\Sdk\Message\Sms; -``` php -$message->getChannels(); -``` +$connection = new ConnectionStream( + /*application_id: */ 0000, + /*application_token:*/ 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' +); -The output is: +$sender = new MessageSender($connection); -``` php -[ - 0 => 'sms' - 1 => 'viber' -] -``` +$sender->send(new Sms($phone_number, $text)); -### JSON support +/* Optional */ -The `BulkGate\Sms\Message` object implements the `\JsonSerializable` interface that lets you convert it via the `json_encode()` to JSON format. +$sender->setTag('sdk'); -``` php -/** @var BulkGate\Sdk\Message\MultiChannel $message */ -$message = new MultiChannel('420777777777', 'test message'); +$sender->setDefaultCountry('cz'); -echo json_encode($message); -``` +$viber_configurator = new ViberConfigurator('Sender'); +$viber_configurator->button('Button Caption', 'https://www.bulkgate.com/'); +$viber_configurator->image('https://www.example.com/example.png', true); +$viber_configurator->expiration(3_600); -``` json -{ - "primary_channel": "viber", - "phone_number": "420777777777", - "country": "cz", - "schedule": null, - "channels": { - "sms": { - "text": "test ", - "variables": { - "variable": "message" - }, - "sender_id": "gText", - "sender_id_value": "Test sender", - "unicode": false - }, - "viber": { - "text": "text_message", - "variables": [], - "sender": "sender", - "button_caption": "Caption", - "button_url": "url", - "image": "image url", - "image_zoom": false, - "expiration": 5 - } - } -} -``` +$sender->addSenderConfigurator($viber_configurator); -### Fluent interface +$sms_configurator = new SmsConfigurator('gText', 'Example', true); -[Fluent interface](https://en.wikipedia.org/wiki/Fluent_interface) is the technique of chaining methods. Every object of this SDK includes fluent interface. +$sender->addSenderConfigurator($sms_configurator); -``` php -$phone_number = new PhoneNumber("603902776", "cz"); -$phone_number->phoneNumber("777777777")->iso("cz"); +$sender->send(new Sms($phone_number, $text)); ``` +## Simple Manual -## Bulk SMS (Campaign) - -The class `BulkGate\Sdk\Message\Bulk` represents the object, which connects all types of messages (BulkGate\Sdk\Message\Sms, BulkGate\Sdk\Message\Viber, BulkGate\Sdk\Message\MultiChannel) to a bulk message (campaign). - -```php -$phone_number = new PhoneNumber("420777777777", "cz"); -$text = new SimpleText("test ", ["variable" => "message"]); -$button = new Button("Caption", "url"); -$image = new Image("image url", false); -$timeout = 5; +- [Message sender](docs/sender.md) +- [SMS](docs/sms_message.md) +- [Viber](docs/viber_message.md) +- [Multi channel message](docs/multichannel_message.md) +- [Bulk message/Campaign](docs/bulk.md) +- [Schedulers](docs/schedulers.md) +- [Configurators](docs/configurators.md) +- [Number checker](docs/number_checker.md) -$sms_message = new Sms($phone_number, $text); -$viber_message = new Viber($phone_number, $text, "sender", $button, $image, $timeout); - -$multi_channel_message = new MultiChannel($phone_number); -$multi_channel_message->sms($text, "gText", "Sender", false); -$multi_channel_message->viber($text, "Sender", $button, $image, $timeout); - -$message = new Bulk([$sms_message, $viber_message, $multi_channel_message]); - -$this->sender->send($message); -``` +## API administration & tokens -### Iterator +[API administration](https://help.bulkgate.com/docs/en/api-administration.html) -You can browse through messsages using the foreach cycle +[API token](https://help.bulkgate.com/docs/en/api-tokens.html) -```php -/** - * @var BulkGate\Sdk\Message\Bulk $bulk_message - * @var BulkGate\Sdk\Message\Base $message - */ -foreach($bulk_message as $message) -{ - echo $message; -} -``` diff --git a/docs/bulk.md b/docs/bulk.md index 3a457da..0042559 100644 --- a/docs/bulk.md +++ b/docs/bulk.md @@ -1,30 +1,36 @@ -## Bulk SMS (Campaign) +Bulk SMS (Campaign) +=================== The class `BulkGate\Sdk\Message\Bulk` represents the object, which connects all types of messages (`BulkGate\Sdk\Message\Sms`, `BulkGate\Sdk\Message\Viber`, `BulkGate\Sdk\Message\MultiChannel`) to a bulk message (campaign). ```php -$sms_message = new Sms('420777777777', new SimpleText("test ", ["variable" => "message"])); +use BulkGate\Sdk\Message\{Sms, Viber, MultiChannel, Bulk}; +use BulkGate\Sdk\Message\Component\{SimpleText, Button} +``` + +```php +$sms_message = new Sms('420777777777', new SimpleText('test ', ['variable' => 'message'])); $viber_message = new Viber( '420777777777', - new SimpleText("test ", ["variable" => "message"]), - "Sender", - new Button("Caption", "https://www.bulkgate.com/") + new SimpleText('test ', ['variable' => 'message']), + 'Sender', + new Button('Caption', 'https://www.bulkgate.com/') ); $multi_channel_message = new MultiChannel($phone_number); -$multi_channel_message->sms(new SimpleText("test ", ["variable" => "message"])); +$multi_channel_message->sms(new SimpleText('test ', ['variable' => 'message'])); $multi_channel_message->viber( - new SimpleText("test ", ["variable" => "message"]), - "Sender", - new Button("GO TO BULKGATE", "https://www.bulkgate.com/") + new SimpleText('test ', ['variable' => 'message']), + 'Sender', + new Button('Go to BulkGate', 'https://www.bulkgate.com/') ); $message = new Bulk([$sms_message, $viber_message, $multi_channel_message]); ``` ### Adding messages -Also you can adding message via `\ArrayAccess` interface. +You can add message via `\ArrayAccess` interface. ```php $message = new Bulk(); @@ -34,7 +40,7 @@ $message[] = new Sms('420777777777', 'test SMS'); ### Iterator -You can go through messsages in bulk message using the foreach cycle +You can go through messages in bulk message using the foreach cycle ```php /** @@ -47,14 +53,16 @@ foreach($bulk_message as $message) } ``` -You can basicaly treat the bulk message as an array +You can basically treat the bulk message as an array ```php -$bulk_message['sms'] = new Sms("420777777777", "text_message"); +$bulk_message['sms'] = new Sms('420777777777', 'text_message'); -isset(bulk_message); +isset($bulk_message['sms']); // true count($bulk_message); unset($bulk_message['sms']); + +isset($bulk_message['sms']); // false ``` diff --git a/docs/configurators.md b/docs/configurators.md index 7f4db31..f6c5fba 100644 --- a/docs/configurators.md +++ b/docs/configurators.md @@ -1,11 +1,8 @@ -# Configurators +Configurators +============= Configurators are classes that provides specialized interface for all message types -## Sms configurator - -This particular configurator provides methods for setting all sender types - ```php use BulkGate\Sdk\Country; use BulkGate\Sdk\MessageSender; @@ -13,6 +10,11 @@ use BulkGate\Sdk\Message\Component\SmsSender; use BulkGate\Sdk\Configurator\{SmsConfigurator, SmsCountryConfigurator, ViberConfigurator} ``` +## Sms configurator + +This particular configurator provides methods for setting all sender types + + ```php $message = new Sms('420777777777', 'text_message'); $sms_configurator = new SmsConfigurator(); diff --git a/docs/multichannel_message.md b/docs/multichannel_message.md index 332bde9..bdc3643 100644 --- a/docs/multichannel_message.md +++ b/docs/multichannel_message.md @@ -1,18 +1,19 @@ -## Multichannel message +Multichannel message +==================== Multichannel allows you to send message via Viber and in case recipient does not own Viber account, SMS message will be send instead. ```php -$phone_number = new PhoneNumber("420777777777", "cz"); -$text = new SimpleText("test ", ["variable" => "message"]); -$button = new Button("Caption", "url"); -$image = new Image("image url", false); +$phone_number = new PhoneNumber('420777777777', 'cz'); +$text = new SimpleText('test ', ['variable' => 'message']); +$button = new Button('Caption', 'url'); +$image = new Image('image url', false); $timeout = 5; $message = new MultiChannel($phone_number); -$message->sms($text, "gText", "Sender", false); -$message->viber($text, "Sender", $button, $image, $timeout); +$message->sms($text, 'gText', 'Sender', false); +$message->viber($text, 'Sender', $button, $image, $timeout); $this->sender->send($message); ``` @@ -23,7 +24,7 @@ You can also change the settings of individual channels after the fact ```php $message->configure(Channel::SMS, $sender_id, $sender_id_value, $unicode); -$message->configure(Channel::VIBER, "sender", $button, $image, $timeout); +$message->configure(Channel::VIBER, 'sender', $button, $image, $timeout); ``` ### Setting channel @@ -31,7 +32,7 @@ $message->configure(Channel::VIBER, "sender", $button, $image, $timeout); Based on used settings interface method channel can be used. ```php -$settings = new \BulkGate\Sdk\Message\Settings\Viber(new SimpleText("text_message"), "sender", $button, $image, $timeout); +$settings = new \BulkGate\Sdk\Message\Settings\Viber(new SimpleText('text_message'), 'sender', $button, $image, $timeout); $message->channel($settings); ``` diff --git a/docs/number_checker.md b/docs/number_checker.md index 43193a7..cab3c1f 100644 --- a/docs/number_checker.md +++ b/docs/number_checker.md @@ -3,13 +3,56 @@ Number checker will validate format and an existence of input phone numbers. ```php -$connection = new ConnectionStream("application_id", "application_token"); +$connection = new ConnectionStream('application_id', 'application_token'); $number_checker = new NumberChecker($connection); + +$result = $number_checker->check(['608123456', '777777777', '420777777777', new PhoneNumber('603777777'), '42061110'], 'cz'); ``` -The output is array where keys are phone numbers and values are true or false +The `$result` is array where keys are phone numbers. ```php -["420777777777" => false] +[ + 608123456 => [ + 'phone_number' => '420608123456', + 'valid' => true, + 'country' => 'cz', + 'call_prefix' => 420, + 'network_code' => '23003', + 'network_name' => 'Vodafone', + ], + 777777777 => [ + 'phone_number' => '420777777777', + 'valid' => true, + 'country' => 'cz', + 'call_prefix' => 420, + 'network_code' => '23003', + 'network_name' => 'Vodafone', + ], + 420777777777 => [ + 'phone_number' => '420777777777', + 'valid' => true, + 'country' => 'cz', + 'call_prefix' => 420, + 'network_code' => '23003', + 'network_name' => 'Vodafone', + ], + 603777777 => [ + 'phone_number' => '420603777777', + 'valid' => true, + 'country' => 'cz', + 'call_prefix' => 420, + 'network_code' => '23002', + 'network_name' => 'T-Mobile', + ], + 42061110: { + 'phone_number': '42061110', + 'valid': false, + 'country': 'cz', + 'call_prefix': 420, + 'network_code': null, + 'network_name': 'unknown' + }, +] ``` diff --git a/docs/schedulers.md b/docs/schedulers.md index 09e7b84..2875765 100644 --- a/docs/schedulers.md +++ b/docs/schedulers.md @@ -1,23 +1,26 @@ -# Schedulers +Schedulers +========== Schedulers are classes that allow scheduling messages at certain intervals or in particular times. ## Simple scheduler -Simple scheduler for sending messages at particular time +Simple scheduler for sending messages at particular time. ```php -$scheduler = new Simple(new \DateTime()); +$scheduler = new Simple(new DateTime('2025-12-13 12:00')); + $scheduler->schedule($message); ``` ## Campaign -Campaign scheduler allows you to start sending messages from particular time by at defined intervals. You can also define how many planned messages will be send out after certain interval. +Campaign scheduler allows you to start sending messages from particular time by at defined intervals. You can also define how many planned messages will be sent out after certain interval. ```php -$scheduler = new Campaign(new \DateTime()); -$scheduler->restriction(2, 2, "hours"); +$scheduler = new Campaign(new DateTime('2025-12-13 12:00')); + +$scheduler->restriction(100 /* messages */, 2, 'hours'); $scheduler->schedule($message); ``` diff --git a/docs/sender.md b/docs/sender.md index a72537b..b29aff1 100644 --- a/docs/sender.md +++ b/docs/sender.md @@ -1,14 +1,7 @@ -BulkGate SMS - PHP SDK -============= +Message sender +============== -[![Downloads](https://img.shields.io/packagist/dt/bulkgate/sms.svg)](https://packagist.org/packages/bulkgate/sms) -[![Latest Stable Version](https://img.shields.io/github/release/bulkgate/sms.svg)](https://github.com/bulkgate/sms/releases) -[![License](https://img.shields.io/github/license/bulkgate/sms.svg)](https://github.com/BulkGate/sms/blob/master/LICENSE) - -- [BulkGate portal](https://portal.bulkgate.com/) -- [BulkGate](https://www.bulkgate.com/) - -## Basic instalation +## Basic installation 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. @@ -19,27 +12,64 @@ composer require bulkgate/php-sdk If you have the package installed just plug in the autoloader. -``` php +```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. -``` php -$connection = new BulkGate\Sdk\Connection\ConnectionStream('APPLICATION_ID', 'APPLICATION_TOKEN'); +```php +$connection = new ConnectionStream(/*application_id: */ 0000, /*application_token:*/ 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'); -$sender = new BulkGate\Sdk\MessageSender($connection); +$sender = new MessageSender($connection); ``` At this point, you are ready to send a message. -``` php -$message = new Sms("420603902776", "test_text"); +```php +$message = new Sms('420603902776', 'test_text'); + +$sender->send($message); ``` The `send()` method will send a message `$message`. -## Nette instalation +### 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](configurators.md) 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); +``` + +## Nette installation You can also use DI container to install this SDK @@ -51,13 +81,22 @@ sdk: application_id: 0000 application_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX sender: - tag: 'sdk' - default_country: cz + tag: 'sdk' # Optional + default_country: cz # Optional configurator: - sms: + sms: # Optional sender_id: gText sender_id_value: 'Example' unicode: true + viber: # Optional + sender: Sender + button: + caption: 'Button Caption' + url: 'https://www.bulkgate.com/' + image: + url: 'https://www.example.com/example.png' + zoom: true + expiration: 3600 # seconds ``` ## API administration & tokens diff --git a/docs/sms_message.md b/docs/sms_message.md index 32c0939..59df825 100644 --- a/docs/sms_message.md +++ b/docs/sms_message.md @@ -1,9 +1,11 @@ -## Transactional SMS +SMS message +=========== The `BulkGate\Sdk\Message\Sms` class represents the object of the SMS message, which consists of the content of the message and the recipient. -``` php +```php use BulkGate\Sdk\Message\Sms; +use BulkGate\Sdk\Message\Component\{PhoneNumber, SimpleText} ``` ### Recipient @@ -11,32 +13,32 @@ use BulkGate\Sdk\Message\Sms; The class accepts as the first argument a phone number that can be entered by a string: ```php -$message = new Sms("420603902776", "test_text"); +$message = new Sms('420603902776', 'test_text'); ``` or accepts an instance of the object `BulkGate\Sdk\Message\Component\PhoneNumber`: ```php -$message = new Sms(new BulkGate\Sdk\Message\Component\PhoneNumber('777777777', 'cz'), 'test message'); +$message = new Sms(new PhoneNumber('777777777', 'cz'), 'test message'); ``` -To obtain a phone number, you can use the print out the class object `BulkGate\Sdk\Message\Component\PhoneNumber`, which always returns a phone number as a string. +To obtain a phone number, you can use the print-out the class object `BulkGate\Sdk\Message\Component\PhoneNumber`, which always returns a phone number as a string. You can also set phone number and iso separately ```php $phone_number = new PhoneNumber(); -$phone_number->phoneNumber("777777777"); -$phone_number->iso("cz"); +$phone_number->phoneNumber('777777777'); +$phone_number->iso('cz'); ``` ### Text of the message -The second parameter is the input of the text of the message. There are also 2 options where the first is to enter text using a `string`, and the other is an instance of the class `component\SimpleText`, or `null`. +The second parameter is the input of the text of the message. There are also 2 options where the first is to enter text using a `string`, and the other is an instance of the class `SimpleText`, or `null`. ```php $phone_number = new PhoneNumber('777777777', 'cz'); -$text = new SimpleText("test ", ["variable" => "message"]); +$text = new SimpleText('test ', ['variable' => 'message']); $message = new Sms($phone_number, $text); ``` @@ -44,11 +46,11 @@ $message = new Sms($phone_number, $text); Of course, you can define text even after creating an instance of an object using the method `text(string $text, array $variables = [])` ```php -$phone_number = new PhoneNumber("603902776", "cz"); +$phone_number = new PhoneNumber('603902776', 'cz'); $message = new Sms($phone_number); -$message->text("test ", ["variable" => "message"]) +$message->text('test ', ['variable' => 'message']) ``` ### Settings @@ -56,8 +58,8 @@ $message->text("test ", ["variable" => "message"]) You can accesss public variable settings to configure [sender_id](https://help.bulkgate.com/docs/en/http-advanced-transactional.html#sender-id-type-sender_id) and unicode ```php -$sender_id = "gText"; -$sender_id_value = "Test sender"; +$sender_id = 'gText'; +$sender_id_value = 'Test sender'; $unicode = false; $message->settings->configure($sender_id, $sender_id_value, $unicode); diff --git a/docs/viber_message.md b/docs/viber_message.md index 821c146..4804f4d 100644 --- a/docs/viber_message.md +++ b/docs/viber_message.md @@ -1,60 +1,63 @@ -## Viber message +Viber message +================ + The `BulkGate\Sdk\Message\Viber` class represents the object of the Viber message, which consists of the content of the message and the recipient. -``` php +```php use BulkGate\Sdk\Message\Viber; +use BulkGate\Sdk\Message\Component\{Button, Image, PhoneNumber, SimpleText} ``` ### Recipient The class accepts as the first argument a phone number that can be entered by a string: -``` php -$message = new Viber("420777777777", "test_text"); +```php +$message = new Viber('420777777777', 'test_text'); ``` or accepts an instance of the object `BulkGate\Sdk\Message\Component\PhoneNumber`: -``` php -$message = new Viber(new BulkGate\Sdk\Message\Component\PhoneNumber('777777777', 'cz'), 'test message'); +```php +$message = new Viber(new PhoneNumber('777777777', 'cz'), 'test message'); ``` -To obtain a phone number, you can use the print out the class object `BulkGate\Sdk\Message\Component\PhoneNumber`, which always returns a phone number as a string. +To obtain a phone number, you can use the print-out the class object `BulkGate\Sdk\Message\Component\PhoneNumber`, which always returns a phone number as a string. You can also set phone number and iso separately -``` php +```php $phone_number = new PhoneNumber(); -$phone_number->phoneNumber("777777777"); -$phone_number->iso("cz"); +$phone_number->phoneNumber('777777777'); +$phone_number->iso('cz'); ``` ### Text of the message -The second parameter is the input of the text of the message. There are also 2 options where the first is to enter text using a `string`, and the other is an instance of the class `component\SimpleText`, or `null`. +The second parameter is the input of the text of the message. There are also 2 options where the first is to enter text using a `string`, and the other is an instance of the class `SimpleText`, or `null`. -``` php +```php $phone_number = new PhoneNumber('777777777', 'cz'); -$text = new SimpleText("test ", ["variable" => "message"]); +$text = new SimpleText('test ', ['variable' => 'message']); $message = new Viber($phone_number, $text); ``` Of course, you can define text even after creating an instance of an object using the method `text(string $text, array $variables = [])` -``` php -$phone_number = new PhoneNumber("420777777777", "cz"); +```php +$phone_number = new PhoneNumber('420777777777', 'cz'); $message = new Viber($phone_number); -$message->text("test ", ["variable" => "message"]) +$message->text('test ', ['variable' => 'message']) ``` ### Settings Third parameter of Viber object is `sender` which is defined as `string`. -``` php -$message = new Viber("420777777777", "text message", "Sender"); +```php +$message = new Viber('420777777777', 'text message', 'Sender'); ``` Viber's functionality provides an option to use buttons and images in your messages @@ -62,12 +65,9 @@ Viber's functionality provides an option to use buttons and images in your messa Button input parameters include caption string and url determining where the button leads Image input parameters include url of image location and boolean that determines whether the image will be zoomable. -``` php -use BulkGate\Sdk\Message\Component\Button -use BulkGate\Sdk\Message\Component\Image; - -$button = new Button("Caption", "url"); -$image = new Image("image url", false); +```php +$button = new Button('Caption', 'url'); +$image = new Image('image url', false); -$message = new Viber("420777777777", "text message", "Sender", $button, $image); +$message = new Viber('420777777777', 'text message', 'Sender', $button, $image); ``` diff --git a/src/MessageSender.php b/src/MessageSender.php index 8079e5c..26fbfb1 100644 --- a/src/MessageSender.php +++ b/src/MessageSender.php @@ -62,7 +62,6 @@ public function setDefaultCountry(?string $country): self $this->default_country = is_string($country) ? mb_strtolower($country) : null; return $this; - } diff --git a/tests/Message/Components/ButtonTest.phpt b/tests/Message/Components/ButtonTest.phpt index 3249821..c03999d 100644 --- a/tests/Message/Components/ButtonTest.phpt +++ b/tests/Message/Components/ButtonTest.phpt @@ -1,6 +1,6 @@