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

```html
[#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:

```php
function project_status_sc($params)
{
    $project = get_variable('project');
    return empty($project['published']) ? 'draft' : 'live';
}
```

```html
[#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](/pt/docs/reference/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.

## Leia a seguir

- [Templates](/pt/docs/concepts/templates/) para o lado da apresentação.
- [Módulos](/pt/docs/concepts/modules/) para empacotar bibliotecas com rotas e dados.