Upgrading
The breaking changes between releases, and what to do about each one when you update.
On this page
Update the framework with Composer, then work down this page from the version you are on. Run phlat registry:check and phlat health:check when you are done. Every change is also listed in Updates.
v0.79.0
deploy.php imports the framework's recipes. Start from phlat/examples/deploy.example.php: import('phlat/deploy/recipe.php') and import('phlat/deploy/provision.php'), then set repository, site_repository and a host with its domain. Move what deploy.env.php held into deploy.php and delete the file. A site deploys to {sites_root}/{domain}, sites_root is /var/www by default, and php_restart and the php:restart task are gone, since a deploy never reloads PHP. PHP-FPM runs as www-data (http_user) and writes only the shared state folders. A host whose PHP runs in a container sets phlat to its own command, which is cd {{release_or_current_path}} && php phlat/addons/cli/phlat by default. A site that keeps its pages in the site repository removes site/pages from shared_dirs.
AddonRegistry::resolve() is alias() and sub(). [$alias, $parts] = $registry->resolve($ref) becomes $alias = $registry->alias($ref) and $sub = $registry->sub($ref), where alias() returns null for an unknown alias and sub() returns a string such as a/b.
A folder with both index.json and index.jsonc throws. Keep one in each view, field, fieldtype and role folder.
v0.78.0
Logout is a POST. Replace any link to /@users/logout with a form or an hx-post to it. A GET no longer signs out. The dash profile/logout page is gone, so drop any pointer to it.
Page::root() is Page::home(). Rename each call.
Ref lookups moved onto Root. App::locate(), App::qualify() and App::aliasRoot() are gone: use $app->site(), $app->core() or $app->addon($alias) and call locate(), lookup() or qualify() on it, or $app->rootOf($alias) for an alias. App::field(), App::owner() and the TemplateFields helpers take or return a Root where they used a path string.
The global router and controller are views/router.php and views/controller.php. Move anything from a views/app/ folder up one level, and replace $page->controller('app') with $page->rootController().
Raw HTML in markdown fields is shown as text. Move markup out of the stored markdown into a field that is meant to hold it. An inlined SVG is cleaned to plain drawing elements, so an upload that relied on scripts, styles or external references loses them.
v0.77.0
{ui field} wraps a control instead of drawing it. Put the control in the tag and move the control's params onto it: {ui field, control: select, name: 'plan', label: 'Plan', options: $plans} becomes {ui field, name: 'plan', label: 'Plan'}{ui select, name: 'plan', options: $plans /}{/ui}. The controls are {ui input} (the default), {ui textarea}, {ui select}, {ui check}, {ui radio} and {ui switch}. The params control, type, value, options, checked, off, placeholder, required and disabled moved to them, and class and attrs on a field now go on the wrapper, not the control. A radio group is {ui field, name: 'x', label: 'X', group: true}{ui radio, name: 'x', options: $options /}{/ui}.
{ui dropdown} lost items and depth. Its panel is the tag's content, so a menu goes inside it: {ui dropdown, title: 'Actions', items: $items /} becomes {ui dropdown, title: 'Actions'}{ui menu, items: $items /}{/ui}, with depth passed to the menu.
v0.76.0
file and image fields store {page uuid}:{filename} only. A bare filename no longer resolves: the edit form shows the stored text with a Clear button and validation fails with "File not found." Prefix each bare value with the uuid of the page whose folder holds the file, through a one-off script that calls Page::save(), then delete the script. A user's avatar is stored the same way, {user uuid}:{filename}, so use User::save() for those. Code that saves a file field writes "{$page->uuid}:{$name}". PageFiles::actualPath() returns null for a filename that contains a path.
The theme border object is strength, and the border utilities are ink variants. Open each theme page and set Strength again, since the old Border values are not carried over: soft and hard keep their names and base is medium. The CSS variables --border-strength-soft, --border-strength and --border-strength-hard are --strength-soft, --strength-medium and --strength-hard. The colors soft, base and hard are gone from the ui preset: border-soft is border-ink-soft, border-base is border-ink-medium and border-hard is border-ink-hard. Every color also has -soft, -medium and -hard variants now, such as bg-primary-soft. Find the old ones with grep -rnE "(border|bg|text|ring|divide)-(soft|base|hard)\b" site addons --include=*.latte, then rebuild your CSS.
v0.74.0
Sign-in is the users addon's. The login page is /@users/login, the dash login view is gone and the core logout view is replaced by @users/logout. Change any link, auth.login value or @dash/login reference to @users/login. A layout that passes $dashLogin to @dash/widget.latte passes $login. A user's files are served under /@users/{uuid}/, no longer under the dash users page.
oidc, totp and mail are off until you list them. Add each one you use to addons in site/config.jsonc, for example "phlat/totp": {}. The default list is now clockwork, ui, users, icons, fonts and dash.
Three config keys moved. timezone is date.timezone, dateTimeFormat is date.format and media.allowed is files.allowed. Rename them in site/config.jsonc and env.json, and in any template that reads them with config().
email.default has no default. It used to be smtp://mailpit:1025. Set it in your config to send mail.
The blocks fieldtype is removed. Make the field a @phlat/stack and move each types.{name} to options.fields.{name} as an inline @phlat/object. Stored entries change from {"type": "hero", "data": {...}} to {"field": "hero", "value": {...}}, so run a one-off script that rewrites them through Page::save(). In templates, $block->type is $entry->name.
richtext stores markdown. It was a plain textarea holding HTML. Stored HTML still renders, but the editor shows raw HTML as text, so rewrite those fields as markdown where editors use them. The core body field is now markdown.
PageFiles::serveRequest() takes only $remainder. Drop the page argument from any call.
v0.73.0
Core's roles/index.json declares only password. The oidc and pinned fields it used to declare are the addons' now. If you have no site/roles/index.json, create one that lists "password": {"extends": "@phlat/password"} and what you use: "oidc": {"extends": "@oidc/oidc"} for sign-in with an identity provider (without it, sign-in fails and /@oidc says so), and "pinned": {"extends": "@dash/pinned"} for each user's own pinned pages (without it, Pin is hidden). If you already have one, add them there.
Role and file templates are named like views. A role or file type can come from an addon as @alias/name, and a template can extends another, so a site/files/svg/index.json that repeated alt and colors is {"extends": "@ui/svg"}. Nothing from an addon applies until you name it.
Color::lighten() and darken() work in OKLCH. They take float $points of OKLCH lightness instead of int $percent of HSL lightness, so the same number gives a different hex. Check any call that needs an exact shade. FieldTypeColor::lighten() and darken() change the same way, and Color::fromHsl() takes floats.
Phlat\Reference is Phlat\Docs\Reference. It moved into the docs addon, which loads it. Code that built reference pages from it needs the docs addon.
The core @phlat/assets view and the dash docs page are gone. A page whose view is @phlat/assets needs a view of its own. The dash no longer has a Docs page: the reference is the docs addon's.
Theme colors gain secondary and accent, and both are required. Open a theme page and set them, or its colors fail to validate. contrast() now picks text by APCA, so some fills change their text color.
v0.72.0
The dash bookmarks field is pinned. Pages listed under Bookmarks on the dash root are not carried over: pin them again from each page's actions menu, or add them to the Pinned field on the dash root.
HTMX moved from the dash addon to ui. A template that loaded p('@dash')->file('htmx.min.js') loads p('@ui')->file('htmx.min.js').
A fragment always lands on itself, and {response} is for the rest. {fragment} no longer takes target:. A {fragment} that had a target: other than its own #name never rendered in the page, so it is now {response} with the same name and options: {fragment 'modal', target: '#modal', swap: 'innerHTML'} is {response 'modal', target: '#modal'}, since a response swaps innerHTML by default. A toast written as {if isFragmentRequest()}{partial '#toasts', swap: 'beforeend'}…{/partial}{/if} can be {response target: '#toasts', swap: 'beforeend'}…{/response}, a response with no name of its own. Find them with grep -rn "target:" site addons --include=*.latte.
{lazy}…{else} is n:lazy with a {placeholder}. Put n:lazy on the element, with its id and options, and move the {else} content into a {placeholder} directly inside it: {lazy 'stack', cache: 300}<div>…</div>{else}<div>…</div>{/lazy} is <div id="stack" n:lazy="cache: 300">{placeholder}…{/placeholder}…</div>. Find them with grep -rn "{lazy " site addons --include=*.latte.
v0.71.0
Db calls go through a connection handle. Db::sql(), Db::transaction(), Db::lastId(), Db::isConnected() and Db::disconnect() are no longer static and take no connection name. Db::sql($sql, $params, 'name') is Db::connection('name')->sql($sql, $params), and Db::transaction($fn, 'name', immediate: true) is Db::connection('name')->transaction($fn, immediate: true). Db::connect() returns the handle, so keep it in a variable when a file uses it more than once. Find them with grep -rnE "Db::(sql|transaction|lastId|isConnected|disconnect)\(" site addons --include=*.php.
Db::connection() returns the handle, not the PDO. Raw PDO calls such as exec(), prepare() and inTransaction() go through ->pdo(). A PRAGMA set right after connecting moves into the third argument, Db::connect($path, 'name', ['journal_mode' => 'WAL']). Find them with grep -rnE "Db::connection\([^)]*\)->(exec|query|prepare|inTransaction|lastInsertId)\(" site addons --include=*.php.
->fetchAll(), ->fetch() and ->fetchColumn() on a Db::sql() result are all(), first() and value(). They are optional, since sql() still returns the statement. Where you switch, first() and value() return null for no row, so a check against false becomes a check against null.
Query and FieldIndex take a Db handle. Pass Db::connection('name') where new Query(...) or new FieldIndex(...) passed the connection name. Find them with grep -rnE "new (Query|FieldIndex)\(" site addons --include=*.php.
v0.70.0
lazy: true is n:lazy. n:fragment="lazy: true" is n:lazy, n:fragment="cache: 300, lazy: true" is n:lazy="cache: 300", and n:inner-fragment becomes n:inner-lazy the same way. n:fragment no longer takes a lazy option. Find them with grep -rnE "lazy: (true|false)" site addons --include=*.latte.
A {fragment} with an {else} is {lazy}. {fragment} no longer takes a placeholder. Rename the tag and its {/fragment} to {lazy} and {/lazy}, keeping the body and {else}. A {lazy} without an {else} is a compile error, so use n:lazy on an element for an empty placeholder. Find the tags with grep -rn "{fragment '" site addons --include=*.latte and check each for an {else}.
Before v0.70.0
This page starts at v0.70.0. A project on an older release updates to v0.70.0 first, then works down from the v0.70.0 entry above. Back up with phlat backup:create before you start. Every change is listed release by release in Updates, which is the detailed history. These are the ones most likely to affect a project.
Content and storage layout
- Pages live in
site/pages/, a git repository of their own, andsite/data/holds only state. - A leading
_marks files the CMS writes (_index.json,_data.json). A definition you write isindex.json. - Users live in
data/users/{shard}/{uuid}: runphlat user:migrate. - Collections are
data/collections/{field}.db, and every item needs a page. - Image variants are named
photo~card.jpg. - Dates are Unix timestamps: run
phlat page:dates --apply. - Run
phlat registry:rebuildafter any of these. SQLite 3.46 or later is required.
Views, fields and templates
- A view is a folder with
index.latteorindex.json, and a field's render template sits beside its definition (site/fields/{name}/render.latte). {companion}became{component}, which is now removed: use{define}.- Fragment and partial targets are
hx-targetselectors, andn:fragmentis named by the element'sid. - An
@aliasrouter orindex.jsoninsite/views/is ignored, and an@aliascontroller extends the owner's.
Addons
- The
adminaddon is nowdash, anddaisyandthemesare merged intoui. - Addons install to
addons/{creator}/{name}, and themountconfig key is gone. - Icons, fonts, Clockwork and oidc are mounted by default.
- Password sign-in is off until
auth.passwordistrue.
ui
.btnis.button, color tokens were renamed, and elements read only their declared params.- The theme is a page with view
@ui/theme, not a config key. - Link
ui.min.css.
PHP API
- Queries: an empty string is never a query, only a declared field can be named in one, and
find()returns pages only. - Cache,
RegistryandCollectiondeletes take a query, and$app->keptreplaces the page-cache methods onApp. - Sessions are written through
Sesonly. Hx::navigate()isHx::redirect(), andPrefsisOptions.- Mutating requests are checked by origin instead of a CSRF token.