## Čo si môžete doprogramovať

Moduly BulkGate dokážu dve veci navyše oproti tomu, čo ponúka administrácia. Oboje
je pre vývojárov — siahnete do kódu svojho e-shopu.

| Rozšírenie | Na čo slúži |
|:--|:--|
| [Vlastná SMS z kódu](#vlastna-sms-z-vasho-kodu) | Odošlete správu odkiaľkoľvek zo svojho kódu, aj z iného pluginu |
| [Vlastné premenné](#vlastne-premenne-v-sablonach) | Doplníte do šablón údaje, ktoré modul sám nepozná — číslo zásielky, vernostné body, čokoľvek z vašej databázy |

Podpora sa líši podľa modulu:

| Modul | Vlastná SMS | Vlastné premenné |
|:--|:--|:--|
| WooSMS (WooCommerce) | Áno | Áno |
| PrestaSMS (PrestaShop) | Áno | Áno |
| CartSMS (OpenCart) | — | Áno |

> [!CAUTION]
> Zneužitie informačnej SMS na propagačné a marketingové účely je **prísne
> zakázané.** Takto smiete posielať len
> [transakčné SMS](https://www.bulkgate.com/sk/centrum-pomoci/vseobecne-informacie/rozdiel-propagacna-transakcna-sprava/).

## Vlastná SMS z vášho kódu

Správa sa odosiela ako transakčná, účtuje sa z peňaženky modulu a prejde rovnakou
cestou ako oznámenia, ktoré modul posiela sám.

### WooSMS

```php
<?php

do_action(
    'bulkgate_send_sms',       // názov akcie
    '420777123456',            // telefónne číslo
    'Ahoj <name>, máš <age> rokov', // text s premennými v lomených zátvorkách
    [                          // hodnoty premenných
        'name' => 'Jano',
        'age'  => '29',
    ],
    [                          // voliteľné nastavenia
        'unicode'     => true,      // diakritika a emoji
        'country'     => 'cz',      // ISO 3166 pre čísla v národnom tvare
        'senderType'  => 'gText',   // typ odosielateľa
        'senderValue' => 'BulkGate', // hodnota odosielateľa
    ]
);
```

### PrestaSMS

```php
<?php

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

### Nastavenie odosielateľa

| `senderType` | Čo znamená | `senderValue` |
|:--|:--|:--|
| `gSystem` | Systémové číslo BulkGate | Nepoužíva sa |
| `gShort` | Short code | Nepoužíva sa |
| `gText` | Alfanumerický odosielateľ | Text, ktorý sa zobrazí príjemcovi |
| `gOwn` | Vlastné telefónne číslo | Číslo v medzinárodnom tvare |

> [!NOTE]
> Starší názov akcie `woosms_send_sms` funguje ďalej, ale pri nových integráciách
> použite `bulkgate_send_sms` — je rovnaký naprieč modulmi.

## Vlastné premenné v šablónach

Modul pri každom oznámení pozbiera údaje o objednávke a zákazníkovi. Týmto
rozšírením do tejto sady pridáte vlastné hodnoty a potom ich použijete v šablóne ako
`<nazov_premennej>`.

### 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 šablóne teraz funguje <tracking_number>

}, 20, 2);
```

### PrestaSMS

Modul volá hook `actionPrestaSmsExtendsVariables` a odovzdáva mu pole s dvoma
kľúčmi — `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 hookov, preto sa rozšírenie robí prepísaním pripravenej triedy
v súbore `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]
> Pri CartSMS súbor prepisujete priamo v module, takže o zmenu prídete pri jeho
> aktualizácii. Zálohujte si ho a po aktualizácii ho vráťte späť.

## Hotové rozšírenia na GitHube

Na bežné prípady — čísla zásielok od dopravcov, vernostné body, platobné
referencie — sú hotové riešenia, ktoré stačí nainštalovať:

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

V priečinku `_ready-made-solutions` nájdete rozšírenia pre konkrétne pluginy —
pri WooSMS napríklad AfterShip, GLS, Nova Poshta alebo sledovanie zásielok, pri CartSMS
vernostné body a čísla zásielok. Vo WooSMS je navyše v priečinku
`woosms-variables-extension` prázdna kostra, z ktorej sa dobre vychádza pri písaní
vlastného rozšírenia.

> [!TIP]
> Skôr než začnete písať vlastný kód, prejdite si hotové riešenia — často stačí jedno
> z nich nainštalovať alebo len upraviť názov tabuľky a stĺpca.