## Co si můžete doprogramovat

Moduly BulkGate umí dvě věci navíc oproti tomu, co nabízí administrace. Obojí
je pro vývojáře — sáhnete do kódu svého e-shopu.

| Rozšíření | K čemu je |
|:--|:--|
| [Vlastní SMS z kódu](#vlastni-sms-z-vaseho-kodu) | Odešlete zprávu odkudkoli ze svého kódu, i z jiného pluginu |
| [Vlastní proměnné](#vlastni-promenne-v-sablonach) | Doplníte do šablon údaje, které modul sám nezná — číslo zásilky, věrnostní body, cokoli z vaší databáze |

Podpora se liší podle modulu:

| Modul | Vlastní SMS | Vlastní proměnné |
|:--|:--|:--|
| WooSMS (WooCommerce) | Ano | Ano |
| PrestaSMS (PrestaShop) | Ano | Ano |
| CartSMS (OpenCart) | — | Ano |

> [!CAUTION]
> Zneužití informační SMS pro propagační a marketingové účely je **přísně
> zakázáno.** Takto smíte posílat jen
> [transakční SMS](https://www.bulkgate.com/cs/centrum-napovedy/obecne-informace/rozdil-propagacni-transakcni-sms/).

## Vlastní SMS z vašeho kódu

Zpráva se odesílá jako transakční, účtuje se z peněženky modulu a projde stejnou
cestou jako oznámení, která modul posílá sám.

### WooSMS

```php
<?php

do_action(
    'bulkgate_send_sms',       // název akce
    '420777123456',            // telefonní číslo
    'Ahoj <name>, je ti <age>',// text s proměnnými v lomených závorkách
    [                          // hodnoty proměnných
        'name' => 'Honza',
        'age'  => '29',
    ],
    [                          // volitelné nastavení
        'unicode'     => true,      // diakritika a emoji
        'country'     => 'cz',      // ISO 3166 pro čísla v národním tvaru
        'senderType'  => 'gText',   // typ odesílatele
        'senderValue' => 'BulkGate', // hodnota odesílatele
    ]
);
```

### PrestaSMS

```php
<?php

Hook::exec('actionPrestaSmsSendSms', [
    'number'    => '420777123456',
    'template'  => 'Ahoj <name>, je ti <age>',
    'variables' => [
        'name' => 'Honza',
        'age'  => '29',
    ],
    'settings'  => [
        'unicode'     => true,
        'country'     => 'cz',
        'senderType'  => 'gText',
        'senderValue' => 'BulkGate',
    ],
]);
```

### Nastavení odesílatele

| `senderType` | Co znamená | `senderValue` |
|:--|:--|:--|
| `gSystem` | Systémové číslo BulkGate | Nepoužívá se |
| `gShort` | Short code | Nepoužívá se |
| `gText` | Alfanumerický odesílatel | Text, který se zobrazí příjemci |
| `gOwn` | Vlastní telefonní číslo | Číslo v mezinárodním tvaru |

> [!NOTE]
> Starší název akce `woosms_send_sms` funguje dál, ale u nových integrací
> použijte `bulkgate_send_sms` — je stejný napříč moduly.

## Vlastní proměnné v šablonách

Modul při každém oznámení posbírá údaje o objednávce a zákazníkovi. Tímhle
rozšířením do té sady přidáte vlastní hodnoty a pak je použijete v šabloně jako
`<nazev_promenne>`.

### 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);
    }

    // v šabloně teď funguje <tracking_number>

}, 20, 2);
```

### PrestaSMS

Modul volá hook `actionPrestaSmsExtendsVariables` a předává mu pole se dvěma
klíči — `variables` a `database`:

```php
<?php

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

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

### CartSMS

OpenCart nemá systém hooků, proto se rozšíření dělá přepsáním připravené třídy
v souboru `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]
> U CartSMS soubor přepisujete přímo v modulu, takže o změnu přijdete při jeho
> aktualizaci. Zálohujte si ho a po aktualizaci vraťte zpět.

## Hotová rozšíření na GitHubu

Na běžné případy — čísla zásilek od dopravců, věrnostní body, platební
reference — jsou hotová řešení, která stačí nainstalovat:

| Modul | Repozitář |
|:--|:--|
| WooSMS | [github.com/BulkGate/woosms-extensions](https://github.com/BulkGate/woosms-extensions) |
| CartSMS | [github.com/BulkGate/cartsms-extensions](https://github.com/BulkGate/cartsms-extensions) |

Ve složce `_ready-made-solutions` najdete rozšíření pro konkrétní pluginy —
u WooSMS například AfterShip, GLS, Nova Poshta nebo sledování zásilek, u CartSMS
věrnostní body a čísla zásilek. Ve WooSMS je navíc ve složce
`woosms-variables-extension` prázdná kostra, ze které se dobře vychází při psaní
vlastního rozšíření.

> [!TIP]
> Než začnete psát vlastní kód, projděte si hotová řešení — často stačí jedno
> z nich nainstalovat nebo jen upravit název tabulky a sloupce.