Pontos de extensão em PHP

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

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

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)