Skip to content

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.

See Organization Management.

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 body closure becomes @section("content").
  • A view's head closure 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

The ZubZet Version Migrator converts every view and layout in your project automatically.

  1. Get the tool: it lives in the migrator/ folder of the zubzet/framework repository; run composer install there
  2. 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") and Z.Request.rootPath/rootHost/absRoot in controllers, models, views, mail views and JavaScript
  • Route:: definitions and groups, reroute(), rerouteUrl(), getUrlParts() and direct REQUEST_URI access
  • .htaccess (RewriteBase), maintenance and login cookie paths, and debug bar usage
  • overrides of email_password_reset and translation keys under email.*
  • the effective rootDirectory per 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_post and 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.


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 host says https:// but is served over plain HTTP loses its logins until host matches the real scheme.
  • A cross-site POST that returns to the application (OIDC form_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 false now switches off. CONFIG_LOGGER_ENABLED=false and 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.ini and 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 calls JSON.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. Use cy.request().

An action that sets its own Content-Type before the helper keeps it.