# PHP-uitbreidingspunten

Libraries, variabelen, template-lokale logica en de data-API voor resources.

## Eigen shortcode-libraries

Eigen shortcode-libraries staan als losse PHP-bestanden in `ext/lib/`:

```
ext/lib/prepare-events.php
```

Het oudere mapformaat wordt voor compatibiliteit nog ondersteund:

```
ext/lib/prepare-events/prepare-events.php
```

Gebruik het mapformaat alleen als de library hulpbestanden nodig heeft die naast het hoofdbestand horen.

De functie moet `<name>_sc($params)` heten, met streepjes vervangen door underscores:

```php
<?php

function prepare_events_sc($params)
{
    // Read a variable set by [#data#] or [#set#]
    $events = get_variable('data.event');

    $result = [];
    $today = date('Y-m-d');
    foreach ($events as $event) {
        if ($event['date'] >= $today) {
            $result[] = $event;
        }
    }

    // Write back - [#repeat data.event#] will now only see future events
    set_variable('data.event', $result);
}
```

In templates aangeroepen zoals elke andere shortcode:

```
[#data event filter=published:1 sort=date|string|asc#]
[#prepare-events#]
[#repeat data.event#]
```

### PHP-API voor variabelen

| Functie | Beschrijving |
|---|---|
| `get_variable('data.event')` | Leest elke templatevariabele via een pad met punten |
| `set_variable('data.event', $value)` | Schrijft een variabele op het opgegeven pad |
| `set_variable_dot('record', $array)` | Schrijft een associatieve array als variabele met punten (`record.field`, `record.uuid`, enzovoort) |


### Libraries voor één template (.inc)

Niet elke library is een herbruikbare bouwsteen. Sommige PHP-bestanden bestaan alleen om één template te bedienen: opstartlogica, datavoorbereiding voor één pagina, of eenmalige configuratie die niet in de gedeelde naamruimte `ext/lib/` hoort.

Zet die als `(shortcode-name).inc`-bestanden naast de template die ze gebruikt:

```
core/tpl/html/
  init.tpl
  create-settings.inc    ← loaded only when called from init.tpl
```

`find_library()` kijkt eerst in de map van de aanroepende template of daar een passende `.inc` staat, voordat het terugvalt op `ext/lib/` of `core/lib/`. Omdat het zoeken de stapel shortcodes volgt, komt het uit bij de map van de binnenste aanroepende template; `[#create-settings#]`, aangeroepen vanuit `core/tpl/html/init.tpl`, vindt dus `core/tpl/html/create-settings.inc` en geen gedeelde library.

De extensie `.inc` betekent "privé / intern". Templates in andere mappen zien deze bestanden niet.

Regels:
- Gebruik `.inc` voor logica die alleen binnen één template zin heeft en elders niet zou worden hergebruikt.
- De functienaam volgt nog steeds de afspraak `<name>_sc($params)`.
- Geef een `.inc`-bestand niet de naam van een gedeelde library (`data.inc`, `url-key.inc`): het lokale bestand zou de gedeelde library binnen die template ongemerkt vervangen.
- `route` is een **verboden** naam voor een shortcode: `route.inc` hoort alleen bij het routingsysteem en kan niet als library worden gebruikt.

---

## PHP-data-API (beschikbaar in `.install.inc` en `route.inc`)

| Functie | Beschrijving |
|---|---|
| `data_create_resource($name, $meta)` | Maakt een nieuwe resource met de opgegeven `.meta`-definitie |
| `data_create($resource, $uuid, $data)` | Maakt een nieuw record |
| `data_read($resource, $uuid)` | Leest één record op UUID |
| `data_exists($resource, $uuid)` | Geeft true als een record bestaat |
| `load_library($name)` | Laadt een shortcode-library zodat de PHP-functies ervan beschikbaar zijn |