Registry
The SQLite index behind find(): query pages by view, published state and content fields, search them, and rebuild when files change outside the CMS.
On this page
What it is
The registry is a SQLite index at site/data/storage/registry.{schema}.{n}.db. It maps every page and user UUID to its path, view, published state, access and timestamps, and indexes content fields for filtering and search, so queries don't scan the page tree.
It is a cache of the files on disk, not a source of truth. It builds itself on first boot, Page::save() and the delete hooks keep it current, and it can always be rebuilt from site/pages/.
Querying
A query is a comma-separated list of conditions, all of which must match:
$app->find('view=article, sort=-created, limit=4');
The result is a collection of Page objects, loaded lazily as you iterate. The same query string works everywhere:
| Call | Searches |
|---|---|
$app->find($query) |
Pages and users, unless you add type=page |
$page->find($query) |
Pages below $page, at any depth |
$page->children($query) |
Direct children only, hidden and unpublished pages excluded |
{find($query)} in Latte |
Pages, from the root |
phlat page:list $query |
The same, from the CLI |
Results include only what the current visitor may open: no unpublished pages, no pages behind an access they don't meet, nothing beneath those. Editors and the CLI see everything. See Publishing and access.
Fields
Structural fields come straight from the index: type, root, depth, view, role, published, access, hidden, locked, path, created, updated. Any other name is a content field, and must be declared by the page's view (or a user's role). A query on an undeclared field throws, and a declared field no page has written yet matches nothing:
$app->find('view=article, tag*=php');
Operators
| Operator | Meaning |
|---|---|
= / != |
Equal / not equal; != keeps records with no value |
*= |
Contains |
^= / $= |
Starts with / ends with |
~= |
The path and every path beneath it: path~=blog is the page at blog and its whole subtree, path~= the whole tree |
< > <= >= |
Comparison; matches numbers only on content fields |
parent=blog matches the direct children of the page at blog, and parent= the pages at the top. It reads = only; path~=blog takes the whole subtree.
Separate alternatives with |: view=article|post. Put ! before any condition to negate it, so !id^=isbn-|upc- matches records whose id starts with neither prefix. A record with no value for the field is kept. type cannot be negated.
Sorting and paging
$app->find('view=article, sort=-created, limit=10, offset=20');
sort=field is ascending, sort=-field descending.
Full-text search
search= runs a ranked match and sorts by relevance unless you give a sort. Each term must match a whole word. Two modifiers loosen that, and neither does anything without search=:
fuzzy=truewidens each term to nearby indexed words, so typos still match.partial=truematches any word that starts with the term, soregisfindsregistry. It matches the start of a word, not the middle.
$app->find('type=page, search=flat file cms');
$app->find('type=page, search=flat file, fuzzy=true');
$app->find('type=page, search=fla, partial=true');
A field's options can set search.weight (high, normal, low) or search.enabled to change how it ranks or whether it is indexed. "query": false keeps a field out of filters and sorting while leaving it searchable; markdown, code and password fields set it.
When it drifts
Changes through Page::save(), the dash or the CLI update the registry. Editing files directly doesn't: hand-edited JSON, pages pulled from git, a restored backup. Then run:
phlat registry:check # report drift and bad UUIDs
phlat registry:check --heal # reindex missing and stale pages, drop orphaned rows
phlat registry:rebuild # re-scan everything from disk
phlat registry:rebuild blog # re-scan one page and its descendants
check also reports malformed _index.json, missing UUIDs and duplicate UUIDs. Those need a person to decide, so --heal never touches them.
A registry schema change between releases drops and rebuilds the index on the next boot.