Concepts
Libraries
Business logic and data preparation in PHP, called as shortcodes.
A library is a PHP file in ext/lib/ that holds business logic or data preparation. It is called from a template as a shortcode, so templates stay logic-free and the logic stays in one testable place.
Write a library
The file name is the shortcode name. The function is that name with dashes turned into underscores, followed by _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#]
The library reads variables, computes what the page needs and writes the result back as variables. The template then prints it.
A library can also return a value, which the shortcode prints. That suits small classifications:
function project_status_sc($params)
{
$project = get_variable('project');
return empty($project['published']) ? 'draft' : 'live';
}
[#badge-[#project-status#]#]
Parameters given in the template arrive in $params: [#price amount=12.5 currency=EUR#] gives $params['amount'] and $params['currency'], and get_param_value($params, 'currency', 'EUR') reads one with a default. A value without a name, as in [#price 12.5#], is the first item, current($params).
Markup stays in templates
A library prepares data; it does not build HTML. When a library needs to render a template, it calls run_buffered() with the template's file path. Keeping markup out of PHP means a designer can change any piece of the interface without touching logic, and logic can be tested without markup.
The PHP toolbox
| Function | Does |
|---|---|
get_variable('data.projects') |
Reads a template variable by its dot path |
set_variable('name', $value) |
Writes a template variable |
set_variable_dot('project', $record) |
Writes a record so its fields are project.title, project.year |
load_library('data') |
Loads another library, for example the data layer |
data_read($resource, $uuid) |
Reads one record |
data_query($resource, [...]) |
Reads a filtered, sorted page of records with the total |
data_create(), data_update(), data_delete() |
Writes records, with validation, indexes, history and events |
env('KEY') |
Reads a setting from .env |
The full list is in PHP extension points.
Libraries for one template
A library that only serves one template can sit next to it as <name>.inc. It is found from that template and its folder only, and stays out of the shared namespace.