## What you can add yourself

BulkGate modules can do two things beyond what the administration offers. Both
are for developers — you reach into your e-shop's code.

| Extension | What it is for |
|:--|:--|
| [Custom SMS from your code](#custom-sms-from-your-code) | Send a message from anywhere in your code, even from another plugin |
| [Custom variables](#custom-variables-in-templates) | Add data the module does not know about to your templates — a tracking number, loyalty points, anything from your database |

Support differs by module:

| Module | Custom SMS | Custom variables |
|:--|:--|:--|
| WooSMS (WooCommerce) | Yes | Yes |
| PrestaSMS (PrestaShop) | Yes | Yes |
| CartSMS (OpenCart) | — | Yes |

> [!CAUTION]
> Misusing informational SMS for promotional and marketing purposes is
> **strictly forbidden.** You may only send
> [transactional SMS](https://www.bulkgate.com/en/helpdesk/general-information/difference-promotional-transactional-sms/)
> this way.

## Custom SMS from your code

The message goes out as transactional, is billed from the module's wallet and
takes the same route as the notifications the module sends on its own.

### WooSMS

```php
<?php

do_action(
    'bulkgate_send_sms',          // the action name
    '420777123456',               // the phone number
    'Hi <name>, you are <age>',   // the text with variables in angle brackets
    [                             // the values of the variables
        'name' => 'John',
        'age'  => '29',
    ],
    [                             // optional settings
        'unicode'     => true,       // diacritics and emoji
        'country'     => 'gb',       // ISO 3166 for numbers in national format
        'senderType'  => 'gText',    // the sender type
        'senderValue' => 'BulkGate', // the sender value
    ]
);
```

### PrestaSMS

```php
<?php

Hook::exec('actionPrestaSmsSendSms', [
    'number'    => '420777123456',
    'template'  => 'Hi <name>, you are <age>',
    'variables' => [
        'name' => 'John',
        'age'  => '29',
    ],
    'settings'  => [
        'unicode'     => true,
        'country'     => 'gb',
        'senderType'  => 'gText',
        'senderValue' => 'BulkGate',
    ],
]);
```

### Sender settings

| `senderType` | What it means | `senderValue` |
|:--|:--|:--|
| `gSystem` | A BulkGate system number | Not used |
| `gShort` | A short code | Not used |
| `gText` | An alphanumeric sender | The text shown to the recipient |
| `gOwn` | Your own phone number | The number in international format |

> [!NOTE]
> The older action name `woosms_send_sms` still works, but use
> `bulkgate_send_sms` for new integrations — it is the same across modules.

## Custom variables in templates

With every notification the module gathers data about the order and the customer.
This extension adds your own values to that set, and you then use them in the
template as `<variable_name>`.

### WooSMS

```php
<?php

use BulkGate\Plugin\{Database\Connection, Event\Variables};

add_action('bulkgate_extends_variables', function (Variables $variables, Connection $database): void
{
    $order_id = $variables->get('order_id');

    $row = $database->fetch('SELECT tracking_number FROM `order` WHERE order_id = ?', $order_id);

    if ($row !== null)
    {
        $variables->set('tracking_number', $row->tracking_number);
    }

    // <tracking_number> now works in the template

}, 20, 2);
```

### PrestaSMS

The module calls the `actionPrestaSmsExtendsVariables` hook and hands it an array
with two keys — `variables` and `database`:

```php
<?php

public function hookActionPrestaSmsExtendsVariables(array $params): void
{
    $variables = $params['variables'];
    $database = $params['database'];

    $variables->set('tracking_number', '1234567890');
}
```

### CartSMS

OpenCart has no hook system, so the extension is done by rewriting a prepared
class in the file `system/library/cartsms/cartsms/src/HookExtension.php`:

```php
<?php

namespace BulkGate\CartSms;

use BulkGate\Extensions;

class HookExtension extends Extensions\Strict implements Extensions\Hook\IExtension
{
    public function extend(Extensions\Database\IDatabase $database, Extensions\Hook\Variables $variables)
    {
        $row = $database->execute($database->prepare(
            "SELECT `tracking_no` FROM `{$database->table('order')}` WHERE `order_id` = %s LIMIT 1",
            [$variables->get('order_id')]
        ))->getRow();

        if ($row)
        {
            $variables->set('tracking_no', $row->tracking_no);
        }
    }
}
```

> [!WARNING]
> With CartSMS you rewrite a file inside the module itself, so you lose the
> change when it is updated. Keep a backup and put it back after each update.

## Ready-made extensions on GitHub

For the common cases — tracking numbers from carriers, loyalty points, payment
references — there are ready-made solutions you only need to install:

| Module | Repository |
|:--|:--|
| WooSMS | [github.com/BulkGate/woosms-extensions](https://github.com/BulkGate/woosms-extensions) |
| CartSMS | [github.com/BulkGate/cartsms-extensions](https://github.com/BulkGate/cartsms-extensions) |

The `_ready-made-solutions` folder holds extensions for particular plugins — for
WooSMS these include AfterShip, GLS, Nova Poshta or shipment tracking, for
CartSMS loyalty points and tracking numbers. WooSMS additionally has an empty
skeleton in the `woosms-variables-extension` folder, a good starting point for
writing your own extension.

> [!TIP]
> Before you start writing your own code, go through the ready-made solutions —
> often one of them is enough as it is, or needs only the table and column names
> changed.