## Ce que vous pouvez ajouter vous-même

Les modules BulkGate savent faire deux choses de plus que ce que propose
l'administration. Les deux s'adressent aux développeurs — vous intervenez dans le
code de votre boutique en ligne.

| Extension | À quoi elle sert |
|:--|:--|
| [SMS personnalisé depuis votre code](#sms-personnalise-depuis-votre-code) | Envoyer un message depuis n'importe quel endroit de votre code, même depuis un autre plugin |
| [Variables personnalisées](#variables-personnalisees-dans-les-modeles) | Ajouter à vos modèles des données que le module ne connaît pas — un numéro de suivi, des points de fidélité, tout ce qui se trouve dans votre base de données |

La prise en charge diffère selon le module :

| Module | SMS personnalisé | Variables personnalisées |
|:--|:--|:--|
| WooSMS (WooCommerce) | Oui | Oui |
| PrestaSMS (PrestaShop) | Oui | Oui |
| CartSMS (OpenCart) | — | Oui |

> [!CAUTION]
> L'utilisation abusive des SMS informatifs à des fins
> promotionnelles et marketing est **strictement interdite.**
> Vous ne pouvez envoyer de cette manière que des
> [SMS transactionnels](https://www.bulkgate.com/fr/centre-d-aide/informations-generales/difference-messages-promotionnels-transactionnels/).

## SMS personnalisé depuis votre code

Le message part comme message transactionnel, il est facturé sur le portefeuille du
module et emprunte la même route que les notifications que le module envoie lui-même.

### WooSMS

```php
<?php

do_action(
    'bulkgate_send_sms',          // le nom de l'action
    '420777123456',               // le numéro de téléphone
    'Bonjour <name>, vous avez <age> ans', // le texte avec les variables entre chevrons
    [                             // les valeurs des variables
        'name' => 'Jean',
        'age'  => '29',
    ],
    [                             // paramètres facultatifs
        'unicode'     => true,       // caractères accentués et emojis
        'country'     => 'fr',       // ISO 3166 pour les numéros au format national
        'senderType'  => 'gText',    // le type d'expéditeur
        'senderValue' => 'BulkGate', // la valeur de l'expéditeur
    ]
);
```

### PrestaSMS

```php
<?php

Hook::exec('actionPrestaSmsSendSms', [
    'number'    => '420777123456',
    'template'  => 'Bonjour <name>, vous avez <age> ans',
    'variables' => [
        'name' => 'Jean',
        'age'  => '29',
    ],
    'settings'  => [
        'unicode'     => true,
        'country'     => 'fr',
        'senderType'  => 'gText',
        'senderValue' => 'BulkGate',
    ],
]);
```

### Paramètres de l'expéditeur

| `senderType` | Signification | `senderValue` |
|:--|:--|:--|
| `gSystem` | Un numéro système BulkGate | Non utilisé |
| `gShort` | Un code court | Non utilisé |
| `gText` | Un expéditeur alphanumérique | Le texte affiché au destinataire |
| `gOwn` | Votre propre numéro de téléphone | Le numéro au format international |

> [!NOTE]
> L'ancien nom d'action `woosms_send_sms` fonctionne toujours, mais utilisez
> `bulkgate_send_sms` pour les nouvelles intégrations — il est identique dans tous les modules.

## Variables personnalisées dans les modèles

À chaque notification, le module rassemble des données sur la commande et le client.
Cette extension ajoute vos propres valeurs à cet ensemble, que vous utilisez ensuite
dans le modèle sous la forme `<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> fonctionne désormais dans le modèle

}, 20, 2);
```

### PrestaSMS

Le module appelle le hook `actionPrestaSmsExtendsVariables` et lui transmet un tableau
à deux clés — `variables` et `database` :

```php
<?php

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

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

### CartSMS

OpenCart ne dispose pas de système de hooks ; l'extension se fait donc en réécrivant une
classe préparée dans le fichier `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]
> Avec CartSMS, vous réécrivez un fichier à l'intérieur même du module ; vous perdez donc
> la modification lors de sa mise à jour. Conservez une sauvegarde et remettez-la en place après chaque mise à jour.

## Extensions prêtes à l'emploi sur GitHub

Pour les cas courants — numéros de suivi des transporteurs, points de fidélité, références
de paiement — il existe des solutions prêtes à l'emploi qu'il vous suffit d'installer :

| Module | Dépôt |
|:--|:--|
| WooSMS | [github.com/BulkGate/woosms-extensions](https://github.com/BulkGate/woosms-extensions) |
| CartSMS | [github.com/BulkGate/cartsms-extensions](https://github.com/BulkGate/cartsms-extensions) |

Le dossier `_ready-made-solutions` contient des extensions pour des plugins précis — pour
WooSMS, notamment AfterShip, GLS, Nova Poshta ou le suivi des envois, pour CartSMS les
points de fidélité et les numéros de suivi. WooSMS propose en outre un squelette vide dans
le dossier `woosms-variables-extension`, un bon point de départ pour écrire votre propre extension.

> [!TIP]
> Avant de commencer à écrire votre propre code, parcourez les solutions prêtes à l'emploi —
> l'une d'elles suffit souvent telle quelle, ou ne nécessite que la modification des noms
> de tables et de colonnes.