# Pontos de extensão em PHP

Bibliotecas, variáveis, lógica local de template e a API de dados dos recursos.

## Bibliotecas de shortcodes próprias

As bibliotecas de shortcodes próprias ficam como arquivos PHP únicos em `ext/lib/`:

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

O formato antigo em pasta ainda é suportado por compatibilidade:

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

Use o formato em pasta só quando a biblioteca precisa de arquivos auxiliares que ficam ao lado do arquivo principal.

A função deve se chamar `<name>_sc($params)`, com os hífens trocados por underlines:

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

Chamada nos templates exatamente como qualquer outro shortcode:

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

### API de variáveis em PHP

| Função | Descrição |
|---|---|
| `get_variable('data.event')` | Lê qualquer variável de template por um caminho com pontos |
| `set_variable('data.event', $value)` | Grava uma variável no caminho indicado |
| `set_variable_dot('record', $array)` | Grava um array associativo como variável com pontos (`record.field`, `record.uuid` etc.) |


### Bibliotecas locais de um template (.inc)

Nem toda biblioteca é um bloco reutilizável. Alguns arquivos PHP existem só para servir a um template: lógica de inicialização, preparação de dados de uma página ou configuração pontual que não pertence ao espaço de nomes global `ext/lib/`.

Coloque-os como arquivos `(shortcode-name).inc` ao lado do template que os usa:

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

O `find_library()` procura primeiro um `.inc` correspondente na pasta do template que chama, antes de recorrer a `ext/lib/` ou `core/lib/`. Como a busca segue a pilha de shortcodes, ela chega à pasta do template chamador mais interno; assim, `[#create-settings#]` chamado a partir de `core/tpl/html/init.tpl` encontra `core/tpl/html/create-settings.inc`, e não uma biblioteca global.

A extensão `.inc` indica "privado / interno". Esses arquivos ficam invisíveis para templates de outras pastas.

Regras:
- Use `.inc` para lógica que só faz sentido no contexto de um template e não seria reutilizada em outro lugar.
- O nome da função continua seguindo a convenção `<name>_sc($params)`.
- Não dê a um arquivo `.inc` o nome de uma biblioteca global (`data.inc`, `url-key.inc`): o arquivo local substituiria a global sem aviso dentro desse template.
- `route` é um nome de shortcode **proibido**: `route.inc` pertence exclusivamente ao sistema de rotas e não pode ser usado como biblioteca.

---

## API de dados em PHP (disponível em `.install.inc` e `route.inc`)

| Função | Descrição |
|---|---|
| `data_create_resource($name, $meta)` | Cria um recurso novo com a definição `.meta` indicada |
| `data_create($resource, $uuid, $data)` | Cria um registro novo |
| `data_read($resource, $uuid)` | Lê um registro pelo UUID |
| `data_exists($resource, $uuid)` | Devolve true se um registro existe |
| `load_library($name)` | Carrega uma biblioteca de shortcodes para que suas funções PHP fiquem disponíveis |