The helpers you have
Grouped by job. Signatures and edge cases live in the code, which is leading. A name not on this page is engine-internal.
Composing a page
| Helper | What it does |
|---|---|
section('name') |
Include theme/sections/name.php. No variables pass through; a section that needs page input is included from the shell. |
snippet('name') |
Include theme/snippets/name.php — head or body. |
svg('name', 'class="icon"') |
Inline assets/icons/name.svg, optionally with attributes on the root element. Inherits currentColor. A <style> that reaches beyond the icon is stripped on the way in (the door refuses it first — see Styling and assets). |
v('/assets/css/site.css') |
Cache-busting version string: ?v=<?= v(...) ?>. Changes only when that file changes. |
The include helpers take a name under their folder (subfolders allowed, no .., no leading slash), resolve draft-aware — in a preview a staged section, snippet or icon wins — and render an HTML comment when the target is missing.
Reading data
| Helper | What it does |
|---|---|
data('type/identifier') |
The entity, localised, with @id and url derived. A slug map is read along the chain — regional variant, base, default — and the entity’s inLanguage names the language whose URL it got; empty only when the slug exists in no language of the chain. @id and url derive from the entity’s own slug; the address of a page is the register’s — rows()’ url, what every projection prints — and the two differ only while two entities claim one slug: enumerate with rows(). |
data_in_lang($entity) |
Whether a data() result belongs to the active language itself (or carries no language — an inLanguage that is no string, a list, names none) — the filter for an enumeration, where a fallback would list a page under the wrong language. rows() and the search apply the same rule to the index, without opening the file. |
data_resolve($stub) |
Expand a {@type, identifier} stub to the full entity. |
rows('blogposting', [...]) |
An overview’s rows without opening an entity — see Overviews below. |
data_ref_identifier($ref) |
The identifier in a reference — a stub, a /slug string or a bare slug. Only a non-empty string names a file: an identifier that is a list, an object, a number or a bool gives null. |
data_image_url($image) |
The URL of an image field, string or ImageObject. |
data_card_presentation($entity) |
Image URL and colours for a card, cascading from image to entity. |
page_identifier() |
The language-invariant key of the entity the router resolved. |
page_type() |
Its type. |
page_notfound() |
Serve the 404 and stop — the theme’s 404 shell for the active language, else the engine’s own page. |
Language
| Helper | What it does |
|---|---|
locale_lang() |
The active language, BCP 47, lower-case. |
locale_list() |
The declared languages. |
locale_string('key') |
An interface word from theme/strings/, in the active language. A miss is logged and audited. |
locale_string_or('key', 'Default text', ['name' => $x]) |
The same with a code default and {placeholder} substitution — where English is an acceptable floor. |
locale_hreflang() |
The alternate-language links for the current page, as the router computed them. seo_head() prints them. |
locale_id($slug) |
The absolute @id/URL for a slug in the active language — for the rare hand-built link. The slug without its leading slash ('about', not '/about'); '' is the root. |
locale_prefix() |
The language prefix of the active language: '' for the default, /<lang> otherwise — for a hand-built path. |
Rungs and fallback: Strings and languages.
Overviews
rows() gives the rows of an overview — a blog index, a services grid, a menu — straight from the site’s index, and you decide the form. It returns plain rows, never HTML: each row carries the Thing floor — name, description, image (a URL; an ImageObject is reduced to it) and url — plus id, type, @type (a string, or null), date (the publication — datePublished, else dateModified — as Y-m-d when it parses: the day the author wrote, in the date’s own offset), lang (the language the entity lives in, as data() stamps it: the page’s, or null for a page-less entity without one) and fragment. That floor is what Schema.org gives every thing and what a card needs; when a card needs more (keywords, a video), read the entity with data().
foreach (rows('blogposting', ['limit' => 10]) as $post) { … $post['name'], $post['url'], $post['date'] … }
rows('itemlist/menu') // the items of that list, in the order the list keeps
rows('itemlist') // the lists themselves
Two sources, one row. A type gives every entity of that type, newest first — by the moment of publication, as the feed orders: a date’s offset counts, a date-time written without one is in PHP’s configured timezone (date.timezone; UTC when unset), and a date without a time is midnight UTC, so a post of the 2nd at 20:00-05:00 sits above one of the 3rd (it is later) while each prints its own day; a date that is no date (januari 2026) sorts last, with the undated. order takes a row field, - for descending: '-date' is the default (on the moment), 'name' alphabetical, 'url' by address; a row without the field sorts last. An itemlist gives the items in the list’s own order — the curated hand. Every reader of a list (rows(), the feed, llms.txt, ld_itemlist()) reads an item the same way: an item that carries @type and a non-empty string identifier names that entity and yields its row, and whatever floor the item carries itself (name or headline, description or abstract, image, url) lays over it — a list may give the same post another title or picture; any other item is a thing written in the list (a menu entry with its own name and url, a heading) and is a row of what it carries, with id and type null. A multi-type item (["BlogPosting", "Article"]) names the folder of its first type, and a row’s @type is always one string or null, so where ['@type' => [...]] matches nothing. An item that names no entity that exists — an identifier no file answers to, an @id alone — is no row, never a hole, and an entry without ListItem.item is not read. The source is a data folder, so its case does not matter: rows('BlogPosting') is rows('blogposting'). limit and offset slice after ordering — the template makes the paging; where filters on exact row fields (['@type' => 'BlogPosting']). where and order see the row as it comes back: where ['url' => null] is what claims no page, where ['url' => $address] that one page, where ['date' => '2026-01-01'] what was published that day.
The rows follow the page: its language (an overview in another language is a page in that language — a type’s rows are what exists in it: an entity its slug map leaves out, or a page-less one written in another language, is no row, before where, order and limit, so a limit counts the page’s own; a list’s item whose entity does not exist in that language is left out there, and a list written in one language has no rows in another — curate per language with a language map as itemListElement, or a written item), and its layer — in a draft preview a staged post sits on top of its overview, in the place publish will give it (a staged new thing takes its place among the others, never after them all), and a staged file that decodes to nothing is gone there, as its page is; on the live path only the live ones show. The url is the register’s own address, the same the sitemap prints, so an entity that claims no page (a list claims none, whatever slug it carries), or whose address the register gave to an earlier claim, has null there — in a preview a live page keeps its address against a staged claim of it. Freshness needs nothing from you: a publish refreshes the rows as it refreshes the page.
A card that needs more than the floor reads the entity per row: foreach (rows('itemlist/featured') as $r) { $e = $r['type'] === null ? null : data($r['type'] . '/' . $r['id']); … }.
Breaking for themes (golf 4)
data_resolve_list()is gone. Looprows('itemlist/<name>')and readdata($r['type'] . '/' . $r['id'])per row where a card needs the whole entity; the audit’s calls check names a theme that still calls it.- A list item is read one way everywhere (above): a reference may carry its own floor and still names the entity; an
@id-only item names nothing; an entry withoutListItem.itemis not read; a reference to nothing is no row. - The audit and
/graphread it the same way: a reference with its own floor that names nothing is astubserror — a live one blocks every publish until the list is fixed — and unpublishing the entity it names is refused; a bare entry, an@idalone, an identifier that is not a string or a reference carrying more than the floor is ashapewarning. - A list follows the page’s language: an item whose entity does not exist in that language is left out there, and a list written in one language has no rows in another.
- A list row’s
@typeis a string ornull;idandtypearenullon a thing written in the list. ld_itemlist('name')gives per item the entity’s@idplus the floor its row shows — never the entity embedded. A theme that wants rich JSON-LD for its items (an Offer’s price, a CreativeWork’s keywords) builds it per row withld_entity().ld_organization()rates the organisation from every review indata/review/about it — on a list or not;itemlist/reviewno longer curates which count.- The feed and
llms.txtshow a list’s entities in their own words, in the list’s order: the list’s floor is an overview’s, and a thing written in the list is no entry. data_ref_identifier()givesnullfor an identifier that is not a non-empty string — a number included.mark()takesnulland marks nothing then —mark($r['id'], $r['type'])on a written thing is safe.- A list is not a page: a slug on an itemlist claims no address.
/<slug>answers 404 and leaves the sitemap, the hreflang and/edit’s Pages; the list’sdata()carries no@idorurl, and arows()row of a list — or a menu item that references one — hasurlnull. The slug still limits the languages the list exists in. Give the page a thing of its own (aWebPageorCollectionPagewith that slug) whose template rendersrows('itemlist/<name>'), and drop the list’s slug — in one publish, so the address never goes dark; the audit warns until then. A theme link to the old address is a dead link, an audit error, once the engine is updated: migrate first. - In a preview an overview comes in the order publish will make: a staged new thing takes its place among the others instead of after them all, a staged file that decodes to nothing is gone from the rows as its page is, and a staged claim of an address a live page holds never takes it.
/graphunder the preview link shows the round too. catalog_root_item()andcatalog_walk_root()are gone — engine-internal; the search reads the rows.- An overview sorts on the moment of publication: a row’s
dateisdatePublished, elsedateModified— an old post edited yesterday no longer tops its list, andllms.txt’s type sections follow — offsets count, and a date that is no date sorts last instead of first.whereandordersee the row as it comes back (url,dateasY-m-d).
The head
| Helper | What it does |
|---|---|
seo_head([...]) |
Title, description, canonical, Open Graph and Twitter tags, hreflang links. title and description required, image and type optional. |
seo_canonical_url() |
The canonical URL of the current page. |
locale_origin() |
The site’s origin, for absolute URLs. |
pwa_head() |
Icons, manifest link, theme colour and service-worker registration. Usually inside a pwa snippet. |
headers_nonce() |
The per-request nonce for an inline <script> that must stay inline under a nonce policy: nonce="<?= e(headers_nonce()) ?>", that attribute and nowhere else. See Styling and assets. |
Structured data
The JSON-LD is built from the entity you render, so it cannot disagree with the page.
| Helper | What it does |
|---|---|
ld($schema) |
Print an array as a <script type="application/ld+json"> block. |
ld_page('Type', $overrides) |
The page bundle: WebSite + Organization + the page entity of Type, with @id and url from the request. Nearly every shell calls this once. |
ld_entity('type/identifier') |
An entity cleaned for output: render fields stripped, every stub in any field turned into an @id reference. |
ld_organization() |
The site’s organisation entity, cleaned, with an aggregateRating over the reviews in data/review/ about it (no itemReviewed, or a stub naming the organisation) that exist in the page’s language — no list needed; a site without data/review/ pays one look at the folder. |
ld_itemlist('name') |
The list data/itemlist/<name>.json as schema, built on its rows: per item the entity’s @id plus the floor the row shows, or a written thing as a Thing; positions 1..n. |
ld_breadcrumb($trail) |
A BreadcrumbList from a trail your functions.php builds. |
ld_faqpage('slug') |
A FAQPage from an entity’s questions. |
A typical head ends with ld(ld_page('Service', ld_entity('service/' . $slug))) and, with trails, ld(ld_breadcrumb($trail)). Referenced people and organisations are harvested into the bundle from their references, whichever field carries them. See Data conventions.
Echoing content
| Helper | What it does |
|---|---|
e($field) |
Escape for HTML — text and attributes alike; every field you echo. Takes anything (a non-string becomes ''), never throws. |
body($html) |
The one sanctioned raw echo, for content fields that carry HTML. Self-flooring: active content is refused. |
Showing a QR
| Helper | What it does |
|---|---|
qr_svg($text, $opt) |
A QR of the text as one inline <svg>: one path in currentColor, crisp edges, a viewBox in modules so CSS sets the size. $opt: ecc (L/M/Q/H, default M), title (an accessible title), class. Empty string when the text does not fit (about 270 bytes at L). |
qr_matrix($text, $ecc) |
The same as rows of 0/1, quiet zone included — for a renderer of your own. |
A QR is a pure function of the text — the same text always gives the same code — so it is rendered wherever it is shown and never stored: on a page it lives in the render cache, in a mail it is computed at send. It is the same helper used to show an authenticator’s enrolment code. Someone who wants a poster makes an asset of the svg, through the MCP like any file.
Proving and hiding a string
| Helper | What it does |
|---|---|
secret_token($bytes, $form) |
Randomness to carry as proof: $bytes (default 16) as hex (default) or base64url. The one recipe behind every engine token, session and nonce — use it for yours. |
secret_sign($text) / secret_verify($text, $tag) |
A 22-character tag that binds the text to this site (HMAC-SHA256 under the site secret). For a link that may be read but not altered: ?u=7&t=<tag> — verify before you act. null/false when the site has no secret. |
secret_seal($text) / secret_open($packet) |
The text hidden in one base64url packet (sodium secretbox, fresh nonce each time) and back. For a value that must travel or rest without showing itself. null when tampered, foreign, or without a secret. |
The site secret is set when the site is stood up; rotating it voids every tag and packet from before. None of these know a request, a path or an actor: what a token opens, how long a tag is honoured, where a packet lands is your template’s call. A random token is its own salt; for a low-entropy value you want to look up without storing it (an address), secret_sign is the keyed hash to use. A password takes password_hash() at the door that asks for one — not this house.
What is deliberately not here
No query language or template inheritance: an overview is rows() — a type from the index, or an ItemList you curate — and anything more is a PHP loop over its rows, with data() per row where a card needs the entity. No section('name', $vars). No helper that writes — templates render, the MCP writes.