## Hva du kan legge til selv

BulkGate-modulene kan gjøre to ting utover det administrasjonen tilbyr. Begge
er ment for utviklere — du går inn i koden til nettbutikken din.

| Utvidelse | Hva den brukes til |
|:--|:--|
| [Egen SMS fra koden din](#egen-sms-fra-koden-din) | Send en melding fra hvor som helst i koden din, også fra et annet programtillegg |
| [Egne variabler](#egne-variabler-i-maler) | Legg til data som modulen ikke kjenner til, i malene dine — et sporingsnummer, lojalitetspoeng, hva som helst fra databasen din |

Støtten varierer fra modul til modul:

| Modul | Egen SMS | Egne variabler |
|:--|:--|:--|
| WooSMS (WooCommerce) | Ja | Ja |
| PrestaSMS (PrestaShop) | Ja | Ja |
| CartSMS (OpenCart) | — | Ja |

> [!CAUTION]
> Det er **strengt forbudt** å misbruke informasjons-SMS til
> markedsføringsformål. På denne måten kan du bare sende
> [transaksjons-SMS](https://www.bulkgate.com/no/hjelpesenter/generell-informasjon/forskjellen-mellom-markedsforings-og-transaksjonsmeldinger/).

## Egen SMS fra koden din

Meldingen sendes som en transaksjonsmelding, belastes modulens lommebok og
går samme rute som varslene modulen sender på egen hånd.

### WooSMS

```php
<?php

do_action(
    'bulkgate_send_sms',          // navnet på handlingen
    '420777123456',               // telefonnummeret
    'Hei <name>, du er <age>',    // teksten med variabler i vinkelparenteser
    [                             // verdiene til variablene
        'name' => 'Ola',
        'age'  => '29',
    ],
    [                             // valgfrie innstillinger
        'unicode'     => true,       // diakritiske tegn og emoji
        'country'     => 'no',       // ISO 3166 for numre i nasjonalt format
        'senderType'  => 'gText',    // avsendertypen
        'senderValue' => 'BulkGate', // avsenderens verdi
    ]
);
```

### PrestaSMS

```php
<?php

Hook::exec('actionPrestaSmsSendSms', [
    'number'    => '420777123456',
    'template'  => 'Hei <name>, du er <age>',
    'variables' => [
        'name' => 'Ola',
        'age'  => '29',
    ],
    'settings'  => [
        'unicode'     => true,
        'country'     => 'no',
        'senderType'  => 'gText',
        'senderValue' => 'BulkGate',
    ],
]);
```

### Avsenderinnstillinger

| `senderType` | Hva det betyr | `senderValue` |
|:--|:--|:--|
| `gSystem` | Et systemnummer fra BulkGate | Brukes ikke |
| `gShort` | En kortkode | Brukes ikke |
| `gText` | En alfanumerisk avsender | Teksten som vises for mottakeren |
| `gOwn` | Ditt eget telefonnummer | Nummeret i internasjonalt format |

> [!NOTE]
> Det eldre handlingsnavnet `woosms_send_sms` fungerer fortsatt, men bruk
> `bulkgate_send_sms` i nye integrasjoner — det er det samme på tvers av modulene.

## Egne variabler i maler

Ved hvert varsel samler modulen inn data om bestillingen og kunden.
Denne utvidelsen legger dine egne verdier til i dette settet, og du bruker dem deretter i
malen som `<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> fungerer nå i malen

}, 20, 2);
```

### PrestaSMS

Modulen kaller kroken `actionPrestaSmsExtendsVariables` og gir den en matrise
med to nøkler — `variables` og `database`:

```php
<?php

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

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

### CartSMS

OpenCart har ikke noe kroksystem, så utvidelsen gjøres ved å skrive om en ferdig forberedt
klasse i filen `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]
> Med CartSMS skriver du om en fil inne i selve modulen, så du mister
> endringen når modulen oppdateres. Ta en sikkerhetskopi og legg den tilbake
> etter hver oppdatering.

## Ferdige utvidelser på GitHub

For de vanlige tilfellene — sporingsnumre fra transportører, lojalitetspoeng,
betalingsreferanser — finnes det ferdige løsninger som du bare trenger å installere:

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

Mappen `_ready-made-solutions` inneholder utvidelser for bestemte programtillegg — for
WooSMS blant annet AfterShip, GLS, Nova Poshta eller sporing av forsendelser, for
CartSMS lojalitetspoeng og sporingsnumre. WooSMS har i tillegg et tomt
skjelett i mappen `woosms-variables-extension`, et godt utgangspunkt for
å skrive din egen utvidelse.

> [!TIP]
> Før du begynner å skrive din egen kode, bør du gå gjennom de ferdige løsningene —
> ofte holder en av dem som den er, eller trenger bare at tabell- og kolonnenavnene
> endres.