Conceitos
Bibliotecas
Lógica de negócio e preparação de dados em PHP, chamadas como shortcodes.
Uma biblioteca é um arquivo PHP em ext/lib/ que contém lógica de negócio ou preparação de dados. Ela é chamada a partir de um template como shortcode, para que os templates continuem sem lógica e a lógica fique num só lugar testável.
Escreva uma biblioteca
O nome do arquivo é o nome do shortcode. A função tem esse nome com os hífens trocados por underlines, seguido de _sc:
<?php
// ext/lib/prepare-projects.php
function prepare_projects_sc($params)
{
$projects = get_variable('data.projects') ?: [];
$year = (int)date('Y');
$recent = array_filter($projects, fn($project) => (int)$project['year'] >= $year - 2);
set_variable('data.recent_projects', $recent);
}
[#data projects filter=published:1#]
[#prepare-projects#]
[#repeat data.recent_projects tpl=card-project#]
A biblioteca lê variáveis, calcula o que a página precisa e grava o resultado de volta como variáveis. O template então o exibe.
Uma biblioteca também pode devolver um valor, que o shortcode exibe. Isso serve para classificações pequenas:
function project_status_sc($params)
{
$project = get_variable('project');
return empty($project['published']) ? 'draft' : 'live';
}
[#badge-[#project-status#]#]
Os parâmetros dados no template chegam em $params: [#price amount=12.5 currency=EUR#] dá $params['amount'] e $params['currency'], e get_param_value($params, 'currency', 'EUR') lê um deles com um valor padrão. Um valor sem nome, como em [#price 12.5#], é o primeiro item, current($params).
O markup fica nos templates
Uma biblioteca prepara dados; ela não monta HTML. Quando uma biblioteca precisa renderizar um template, ela chama run_buffered() com o caminho do arquivo do template. Manter o markup fora do PHP significa que um designer pode mudar qualquer parte da interface sem mexer na lógica, e a lógica pode ser testada sem markup.
A caixa de ferramentas do PHP
| Função | Faz |
|---|---|
get_variable('data.projects') |
Lê uma variável de template pelo caminho com pontos |
set_variable('name', $value) |
Grava uma variável de template |
set_variable_dot('project', $record) |
Grava um registro para que seus campos sejam project.title, project.year |
load_library('data') |
Carrega outra biblioteca, por exemplo a camada de dados |
data_read($resource, $uuid) |
Lê um registro |
data_query($resource, [...]) |
Lê uma página filtrada e ordenada de registros, com o total |
data_create(), data_update(), data_delete() |
Grava registros, com validação, índices, histórico e eventos |
env('KEY') |
Lê uma configuração do .env |
A lista completa está em Pontos de extensão em PHP.
Bibliotecas de um único template
Uma biblioteca que serve só a um template pode ficar ao lado dele como <name>.inc. Ela só é encontrada a partir desse template e da pasta dele, e fica fora do espaço de nomes compartilhado.