Migrating from v1.2.0 to v1.3.0¶
Table of Contents¶
New Features¶
Katana Blade render engine¶
Views are now rendered with Katana, a standalone implementation
of the Blade templating language. This brings real template
inheritance, reusable <x-...> components, shared partials and the full set of Blade directives
(@if, @foreach, @forelse, @include, and more) to your views. See the rewritten
Views documentation for what is now possible.
UUIDs on authentication objects¶
Users, roles, groups, organizations, sessions and api keys (and the z_file table) carry a UUID
next to their numeric ID. It is the identifier meant to leave the application - URLs, REST payloads,
anything handed to a third party - because it does not reveal how many records exist and cannot be
guessed by counting up. The numeric ID stays the internal key.
Every object that can be retrieved by ID can also be retrieved by UUID, and every object exposes its own:
$user = User::byUuid($uuid);
$roles = Role::byUuids(...$uuids);
user()->uuid;
$user->uuid();
$organization->uuid();
For a session or an api key the UUID is the only identifier safe to publish - the token
authenticates whoever presents it, so it belongs in a cookie or an Authorization header and
nowhere else. Use the UUID to address a session in a "your active sessions" list:
$session = Session::byUuid($uuid); // scoped like byId(): never returns an api key
$key = APIKey::byUuid($uuid);
See Access Control for the full API.
Organization self-management¶
Members can manage their own organization in the Z-Admin panel at /z/organization: rename it
(z.organization.rename), invite existing accounts by link (z.organization.invite) and hand out
roles that are released to organizations (z.organization.roles). The sidebar entry and the
dashboard card show up with z.organization.manage. A role is released with the new
Organizations may assign this role to their members checkbox on its page under Roles. Nothing is
released after the upgrade, so organizations can only hand out roles once you tick it.
Two factor authentication¶
Accounts can protect their logins with a time based one time password from an authenticator app.
Users set it up on their profile page. A login of an account with two factor then asks for the code
in a modal before the session starts, and $req->requireFreshTwoFactor() guards a single action
behind a check within two_factor_freshness_seconds (defaults to 900).
The modal ships with <x-zubzet::body/>. A layout that leaves out the body essentials cannot finish
a two factor login until it renders <x-zubzet::authentication.two-factor/> itself.
See Two Factor Authentication.
Profile page¶
Every logged in account has a profile page at /z/profile: password change, two factor, sessions
and api keys. It is built from the zubzet::account.* components, which can be placed on any page.
See Profile.
A password change ends every login of the account but no longer its api keys, and neither does
$user->clearSessions(). Revoke keys through APIKey::byUser() where a password change used to end
them.
Requirements¶
MariaDB 11.7 or newer¶
v1.3.0 raises the minimum database server to MariaDB 11.7. Older servers are no longer supported.
ZubZet targets MariaDB, not MySQL: the framework-bundled migrations use MariaDB-only syntax
(ALTER TABLE ... ADD COLUMN IF NOT EXISTS), which MySQL rejects. The development stack and the
e2e suite run MariaDB 11.8.
Check what your server runs:
SELECT VERSION();
The intl PHP extension¶
The framework now requires the PHP extension intl in its composer.json, because
translations pick the locale of a visitor with it.
composer install stops on a PHP without the extension. The ghcr.io/zubzet/php images include it.
Check what your PHP has:
php -m | grep intl
Breaking Changes¶
Views are now Blade templates¶
The old view format, a PHP file returning head and body closures, has been replaced by Blade
.blade.php templates. The change is mechanical and the migrator
applies it for you:
- A view's
bodyclosure becomes@section("content"). - A view's
headclosure becomes@section("head"). - Every view starts with
@extends($layout), so the view plugs into the layout the controller chose. - Layouts drop their
$body($opt)/$head($opt)calls in favor of@yield("content")/@yield("head"), and the framework essentials become the<x-zubzet::head :opt="$opt"/>and<x-zubzet::body :opt="$opt"/>components.
Before:
<?php return ["body" => function($opt) { ?>
<h1><?= $opt["title"] ?></h1>
<?php }]; ?>
After:
@extends($layout)
@section("content")
<h1>{{ $opt["title"] }}</h1>
@endsection
Plain PHP still works inside a .blade.php file, so raw <?php ?> blocks in your views keep running
unchanged. See the Views documentation for the full picture.
Requests from other sites are rejected¶
Every request that can change state (POST, PUT, PATCH, DELETE, ...) is checked for CSRF by
the headers the browser sets. A form or fetch() call from a site that is not allowed is answered
with 403 until its origin is listed. GET, HEAD and OPTIONS are not checked, so links,
redirects and callbacks keep working. See step 7.
Upgrade Steps¶
Follow these steps to upgrade your project to v1.3.0.
1. Upgrade the database server first¶
Bring the server to 11.7 or newer before applying the migrations of this release. With the
Docker stack, bump the mariadb image in packaging/docker/docker-compose-base.yml and recreate
the container:
image: mariadb:11.8
2. Automated migration (recommended)¶
The ZubZet Version Migrator converts every view and layout in your project automatically.
- Get the tool: it lives in the
migrator/folder of the zubzet/framework repository; runcomposer installthere - Preview the changes with a dry run, then apply them:
php application.php upgrade {PATH_TO_YOUR_PROJECT} 1.2.0 1.3.0 --dry
php application.php upgrade {PATH_TO_YOUR_PROJECT} 1.2.0 1.3.0
The migrator bumps the framework dependency, adds the new z_settings.ini keys and rewrites every return [...] view and layout to Blade
(.blade.php), including the section, @extends and essentials-component changes above. It also
removes app-local copies of Z.js, since the framework serves the current one itself, and adds a
.htaccess to webroot/uploads/ (see step 11).
Review each prompted change before accepting it.
3. Review your migrated views¶
The conversion is output preserving, but it is worth skimming the result. Views that already used raw
<?php ?> keep it verbatim, and anything the framework could not classify is left as raw PHP rather
than guessed at. Once you are comfortable with Blade, you can gradually adopt directives like
@foreach or components where they make a template clearer. The
Views documentation covers what is available.
4. Apply the database migrations¶
The framework-bundled migrations are applied by the project's normal start/seed flow
(npm run start, which runs db:seed → migrations then seed) or directly with:
docker exec application php index.php db:migrate
New since v1.2.0:
| Migration | Change |
|---|---|
2026-09-02_user_locale_bcp_47.sql |
Adds the nullable z_user.locale_bcp_47, the user's preferred locale. |
2026-09-07_session-api-key.sql |
Adds z_logintoken.name, is_permanent and is_apikey. |
2026-09-08_session-device-and-ip.sql |
Adds z_logintoken.device, reason, ip_creation and ip_last. |
2026-09-08_uuid.sql |
Adds the NOT NULL, indexed uuid column (native UUID type) to z_user, z_role, z_organization, z_logintoken and z_file. |
2026-09-09_session-expires-at.sql |
Adds the nullable z_logintoken.expires_at (TIMESTAMP), the fixed expiry that overrides the computed session lifetime. |
2026-09-17_session-last-used-and-token-index.sql |
Adds the nullable z_logintoken.last_used (TIMESTAMP). |
2026-09-21_two-factor-challenge.sql |
Creates z_two_factor_challenge for the login's two factor step, and adds z_logintoken.last_two_factor, z_user.two_factor_secret and z_user.two_factor_confirmed_at. |
2026-09-21_2_session-two-factor-tries.sql |
Adds z_logintoken.remaining_two_factor_tries (defaults to 5). |
2026-09-23_group-org-assignable.sql |
Adds z_role.is_org_assignable (TINYINT(1), default 0), which releases a role or group to organizations. |
2026-09-23_organization-invite.sql |
Creates z_organization_invite, the invitation links of organizations. |
2026-10-02_session-token-index.sql |
Adds a unique index on z_logintoken.token, so the session lookup no longer scans the table. |
2026-11-09_organization-permissions.sql |
Creates z_organization_permission and z_organization_role, which every permission check reads. |
If you manage schema by hand, the equivalent statements are idempotent (... IF NOT EXISTS).
5. Check code that builds URLs from the root directory¶
v1.3.0 fixes how a non-empty rootDirectory is handled. With an empty rootDirectory (the
default, and what the Docker stack sets through CONFIG_ROOTDIRECTORY: "") nothing changes. Below
a root directory such as sub:
| Value | v1.2.0 | v1.3.0 |
|---|---|---|
$opt["root"], $req->getRootFolder(), Z.Request.rootPath |
/sub |
/sub/ |
$opt["absRoot"], $opt["application_root"], $req->getRoot(), config("root"), Z.Request.absRoot, Z.Request.rootHost |
https://example.com/sub |
https://example.com/sub/ |
Route::get("/hello") on /sub/hello |
no match (compared against the full path) | matches |
getUrlParts() of /sub/a/b with rootDirectory = sub/ |
["b"] (the slash counted as a segment) |
["a", "b"] |
$res->reroute(["a", "b"]) |
404 (the root directory was missing from the rerouted path) | runs a/b |
The only code that needs a change is code that adds its own slash after the root. The router
answers the resulting /sub//login like /sub/login, so such links keep working until cleaned up:
// before: /sub//login after the upgrade
$opt["root"] . "/login"
// after
$opt["root"] . "login"
Search your project for a slash right after any of the values in the first two rows (root"] . "/,
root ?>/, {{ $opt["root"] }}/, rootPath + "/", ...) and for paths with a leading slash
handed to helpers that prepend the root themselves (rerouteUrl("/, Z.Request.root("/). Routes,
reroute() calls and getUrlParts() need no change as long as they are written relative to the
root directory, which is the only form that worked before.
A cookie path taken from getRootFolder() now ends with a slash as well, so the browser no longer
sends that cookie on the bare /sub. Pass rtrim($req->getRootFolder(), "/") ?: "/" instead, as
the framework does for its maintenance cookie.
What was checked¶
Before the release, the change was checked against eleven existing applications, built on framework versions from v0.11 to v1.3.0-alpha, by reading their code against the old and the new behaviour. Each application was checked for:
- every concatenation of
$opt["root"],$opt["absRoot"],getRoot(),getRootFolder(),config("root")andZ.Request.rootPath/rootHost/absRootin controllers, models, views, mail views and JavaScript Route::definitions and groups,reroute(),rerouteUrl(),getUrlParts()and directREQUEST_URIaccess.htaccess(RewriteBase), maintenance and login cookie paths, and debug bar usage- overrides of
email_password_resetand translation keys underemail.* - the effective
rootDirectoryper environment: the INI value, the Docker setup and the production and staging deployments
Result:
| Setup found | Applications | Outcome |
|---|---|---|
Deployed with CONFIG_ROOTDIRECTORY: "" (every production, staging and Docker environment) |
11 | Identical values, routes and reroutes |
INI rootDirectory without a trailing slash (sub, also with spaces) |
5 | Links like /sublogin and routes below the root are fixed |
INI rootDirectory with a trailing slash (sub/) on v1.2 |
2 | The autorouter no longer strips the controller, links are fixed |
INI rootDirectory with a trailing slash (sub/) on v0.11 to v1.0 |
2 | Identical values, those versions already used the value verbatim |
INI rootDirectory empty |
2 | Identical values |
A slash added after the root (root . "/path") |
0 | Would keep working with a doubled slash, the change shown above removes it |
Route:: paths that include the root directory |
0 | Would need the root directory removed |
Root directories with spaces (My App) behave the same: the router decodes the request path
before stripping the root directory, and getUrlParts() counts the encoded segment as one, so both
agree on real requests and on reroutes.
The e2e suite serves the application below /sub as well and covers this in
tests/cypress/e2e/core/root-directory.cy.js (links, assets and the debug bar, Route::
definitions, reroutes, a doubled slash after the root, the maintenance cookie, the password reset
mail) and tests/cypress/e2e/core/request.cy.js (getUrlParts() with one, two and slash-wrapped
segments, and a doubled slash after them).
6. Send the login warning yourself if you relied on it¶
Too many failed logins no longer send the "Security alert" email to the account owner; the login
is still blocked and logged as ACCOUNT_LOGIN_RATE_LIMITED. The email_too_many_logins view, the
z_login_too_many_tries table and the z_loginModel helpers around it stay, so no migration is
needed, but the framework no longer calls them. To keep the warning, send it when
checkLoginTries() returns false:
if(!$user->checkLoginTries()) {
$res->sendEmailToUser($user->id(), "Security alert", "email_too_many_logins.php", [
"date" => date("Y-m-d H:i:s"),
"ip" => $req->ip(),
]);
}
$req->ip() returns the first value that is set out of HTTP_CLIENT_IP, HTTP_X_FORWARDED_FOR and
REMOTE_ADDR, so REMOTE_ADDR, the only address the client cannot choose, is used only when
neither header is present. The framework does not strip these headers and does not know a list of
trusted proxies, so any client can send them and the address is spoofable. X-Forwarded-For may
also hold a comma separated chain. The same value ends up in ip_creation of sessions and two
factor challenges and in ip_last of sessions. The view prints it unescaped. Validate it with
filter_var($ip, FILTER_VALIDATE_IP) before it goes into the mail, otherwise an attacker can put
HTML into a security mail to the account owner, and do not use it as proof of where a login came
from unless your proxy overwrites both headers.
checkLoginTries() returns false on every blocked attempt, so the example sends one mail per
attempt. Throttle it, the removed code sent at most one mail per 10 minutes.
7. Allow the sites that send requests to your application¶
Requests from other sites are answered with 403
Every request but GET, HEAD and OPTIONS is now checked against Cross-Site Request
Forgery. A form post or fetch() call that a page of another site starts is rejected with
403 unless that site is allowed. Check every endpoint that is called from outside before
you deploy, and every action that changes state on a GET.
The check judges a request by the headers the browser sets (Sec-Fetch-Site, Origin), with no token, cookie or form field, so forms, Z.Forms, Z.Request and your own
fetch() calls keep working unchanged. A request with neither header (curl, servers, webhooks)
passes, and one with an Origin but no Sec-Fetch-Site (old browsers, plain http://) only meets
csrf_blocked_origins. A checked request whose page hides its Origin (no-referrer, a sandboxed
iframe) passes only from the application's own origin.
What is rejected now:
- Form posts from other sites, among them OAuth and SAML callbacks by
form_postand payment returns that post back. - Pages of your own on other hosts or subdomains that post to the application.
fetch()calls from other origins that change state; their CORS preflight passes.
Links, redirects, embedded images and every other GET, HEAD or OPTIONS pass. An action that
changes state on a GET is therefore unprotected: move it to a POST, or call
$req->csrfBlockAdditionalMethod("GET", "HEAD") at its start, as the framework's logout does. See
Protecting a normally safe method.
The migrator adds the three settings with their defaults, which accept requests from the application's own origin and from no page at all (a typed URL, a bookmark) only:
csrf_allow = same-origin
csrf_trusted_origins =
csrf_blocked_origins =
List the origins that legitimately send users or requests to the application in
csrf_trusted_origins, for example the identity and the payment provider. Each entry is one
origin exactly as the browser sends it, scheme://host[:port] without path, trailing slash or default
port; wildcards are not supported. csrf_allow = any lets every site in, for an API without a
cookie session. When every
subdomain of your site is yours, csrf_allow = same-site accepts all of them, and
csrf_blocked_origins takes single ones out again. See
CSRF Protection for the decision, a table of common
setups and the limits.
8. Check what depends on the session cookie¶
The z_login_token session cookie and the maintenance bypass cookie now carry SameSite=Lax, and
Secure whenever the host setting starts with https://. This can break three things:
- A deployment whose
hostsayshttps://but is served over plain HTTP loses its logins untilhostmatches the real scheme. - A cross-site
POSTthat returns to the application (OIDCform_post, SAML, payment returns) arrives without the session cookie. - A request from a cross-site iframe has no session cookie either.
9. Set encryption_key if you use secrets¶
encryptSecret() and decryptSecret() need the encryption_key setting, at least 32 bytes. Set it
via CONFIG_ENCRYPTION_KEY and keep an empty encryption_key = line in z_settings.ini, because
environment variables only override settings that exist there. Values encrypted with a key cannot be
recovered once it is changed or lost.
See Secrets.
10. If requests fail with "Illegal mix of collations"¶
Framework tables are now created as utf8mb4 / utf8mb4_uca1400_ai_ci. Existing installations are
not converted, because converting rewrites every table. If tables created under different server
defaults make queries fail with Illegal mix of collations, convert the framework tables once,
ideally in a maintenance window:
docker exec application php index.php repair:database-collation
Add --include-app-tables to convert the application tables too and to set the database default.
See Console Commands.
11. Protect other upload folders in the webroot¶
Files in webroot/uploads/ are only served now, never run through PHP: the migrator adds a
.htaccess there. Without it, an upload field that accepts the php extension lets anyone run code
by opening the uploaded file. If uploadFolder or an upload() call points to another folder in the
webroot, put the same .htaccess there:
<Files "*">
SetHandler None
</Files>
13. Check code that reads session tokens¶
Newly issued session and api key tokens are zub-sha256- plus 64 hex characters (75 in total) and
are stored hashed. For such a token token() returns the plain value only on a session created by
add() or byToken(); on one loaded by any other retriever it is null, and storedToken() returns
the stored value. Sessions and api keys issued before the upgrade stay valid and keep returning their
token from every retriever, with a deprecation notice that showErrors = 2 promotes to an exception,
so development setups see it right away. Widen anything that validates a token by its length, and compare
z_logintoken.token in your own SQL against storedToken() or LoginToken::hash($token).
14. Check code that relied on corrected behaviour¶
v1.3.0 fixes a number of functions that did not do what their documentation said. Code that depended on the old result has to be adapted. Most projects are not affected by any of these.
| What | Before | Now |
|---|---|---|
shortenStr($text, $limit) |
A text that fits got a trailing space, a text exactly as long as the limit was cut, and a limit below 3 gave a longer result | A text that fits is returned unchanged, the result is never longer than the limit |
$req->validateForm($fields, []) |
An empty array was replaced by the POST | Only null falls back to the POST, an empty array is validated as it is |
->in([...]), ->checked() |
Loose comparison: 01, 1.0 and +1 matched 1 |
Compared as text. A list of integers still accepts the posted "2" |
->regex(...) |
A value passed when only a 0 was left over, and failed when it consisted of exceptions only |
Passes exactly when nothing is left over |
$user->isVerified() |
An unreadable verified value (empty text, 1, yes) counted as verified |
Counts as not verified. A date and NULL behave as before |
| Migration file names | A date like 2025-02-30 was accepted and sorted as March 2 |
db:migrate rejects a date that is not in the calendar |
login_scope_allow_subdomains = true |
Only the quoted text "true" switched it on |
Every spelling of true does, see below |
$res->success(), error(), formErrors(), generateRest() |
Sent as text/html |
Sent as application/json to a client that asks for it in its Accept header, as text/plain to every other, see below |
$req->isAction($name) |
Loose comparison, and isAction("") was true without a posted action |
Compared as text, false without a posted action |
$req->getParameters($offset, 1, $value) |
Loose comparison: 05 matched 5 |
Compared as text |
$req->getUrlParts() |
The path /0 had no parts, and the root directory was cut off any path |
/0 gives ["0"], and the root directory is only cut off a path that starts with it |
$req->store |
Empty after $res->reroute() |
Handed on to the rerouted request |
$req->getBody() |
null for a body of 0 |
"0" |
Settings that switch something on or off (allow_env_config, db_ssl, db_persistent,
logger_enabled, health_endpoint_enabled, debugbar_hide_internal_queries,
login_scope_allow_subdomains) are now read with
configSwitch(): true, on,
yes and 1 are on, false, off, no, 0 and an empty value are off, quoted or not. Two
things follow:
- The text
falsenow switches off.CONFIG_LOGGER_ENABLED=falseand a quoted"false"used to count as on, because any text is truthy to PHP. - Any other value stops the application with an error that names the setting. Check these settings
in
z_settings.iniand in your environment variables for a typo or a placeholder.
A project with an unquoted login_scope_allow_subdomains = true gets its login cookie shared with
its subdomains after the upgrade, which is what the line asks for but did not do before.
REST replies are no longer sent as HTML. Sent as text/html, markup inside a value ran in a
browser that opened the endpoint. A plain $.post() or $.ajax() still receives text, so code that
calls JSON.parse(data) on the answer keeps working. Three things can need a change:
- JavaScript that asks for JSON (
dataType: "json",$.getJSON) and callsJSON.parse()on the result. It never worked with a reply jQuery had already parsed;Z.Request.parseAnswer(data)takes both forms. - Code that inserts the reply of a REST helper into the page as HTML. Render a view for that.
- A Cypress spec that opens a REST endpoint with
cy.visit(), which only accepts HTML. Usecy.request().
An action that sets its own Content-Type before the helper keeps it.