Upgrading to 6.0

This page brings an existing installation to the current Exponential 6.0 line: from any earlier 6.0.x release, or from eZ Publish 5.4 or 5.90. The newest release is 6.0.14 (7 June 2026); the 6.0.15 line is in development on the main branch, and Composer installs it with the constraint ~6.0.15 (the main branch is also known as 6.0.x-dev). Plan twenty minutes for a small site. The risky step is the database, which is why the first step is a backup.

Run every command from the installation root (the directory with index.php, autoload.php, bin/ and settings/), as the user the site runs as. When you run a script as root, add --allow-root-user. ./console is a shortcut for php bin/php/console.

1. Prerequisites

• PHP. Exponential 6.0.15 runs on PHP 8.0 to 8.5 (PHP 7.4 is usable without support). The releases 6.0.8 to 6.0.14 require PHP 8.1. Use the newest PHP your system offers. See PHP 8.0 support.
• Database. SQLite 3, PostgreSQL, MongoDB, MariaDB, Oracle (through the ezoracle extension) and MySQL. See Database support.
• Composer, and shell access to the server.
• Read the release notes of every version you pass, in doc/changelogs/6.0/ of the new code (for example Changelog 6.0.15).
• Try it on a copy first, then upgrade the live site in a planned window. Maintenance mode answers visitors with a 503 page while you work:

php bin/php/maintenance.php on --message="Back soon" --until=30m --allow-root-user
php bin/php/maintenance.php status --allow-root-user

2. Back up

Back up the database and the files together, with the site in maintenance mode. Use your own user, database and file names:

mysqldump --single-transaction -u USER -p DATABASE > backup-before-update.sql      # MySQL or MariaDB
pg_dump -U USER DATABASE > backup-before-update.sql                               # PostgreSQL
sqlite3 var/storage/sqlite3/exponential.db ".backup 'backup-before-update.db'"     # SQLite: the path of your database file
tar czf backup-files-before-update.tar.gz var settings/override settings/siteaccess extension design composer.json composer.lock
git rev-parse HEAD > backup-code-revision.txt      # a Git installation
cp composer.lock backup-composer.lock              # a Composer project
./console exp:info --json --no-logo > before.json  # the system card, to compare afterwards

A backup you have never restored is only a hope: restore it once on another machine. Before the upgrade, Setup > Upgrade check in the administration (or php bin/php/checkmanifest.php --all --extensions) lists the kernel files you changed; move such changes into an extension or settings/override/ first, or the upgrade overwrites them. See The upgrade check.

3. Put the new code in place

Never let a tool overwrite settings/override/, settings/siteaccess/, your own extensions or your own designs.

A Composer project (the kernel is the package se7enxweb/exponential): set the version constraint in your project's composer.json if needed, then update the kernel. Extensions installed with Composer are updated the same way, one package at a time, after reading their release notes.

composer update se7enxweb/exponential

A Git clone of https://github.com/se7enxweb/exponential.git: fetch, then merge the release tag (or origin/main for the current state of the line), then install the libraries composer.lock names. Sort tags by version, never by name alone:

git fetch --tags
git tag -l 'v6.0.*' --sort=version:refname | tail -5
git merge v6.0.14          # or: git merge origin/main
composer install

From eZ Publish 5.4 or 5.90: take a new checkout of Exponential 6 and copy your settings/override/, settings/siteaccess/, extension/ and design/ into it, or change the constraint of se7enxweb/exponential in your project's composer.json and run composer update se7enxweb/exponential.

Exponential Velocity, the application server, is part of Exponential as of 6.0.15 (the package se7enxweb/exponential-velocity) and is updated with the rest. Then compare .htaccess and config.php with the new templates; nothing is written without --apply:

./console exp:setup:status
./console exp:setup:htaccess
./console exp:config:list

4. Upgrade the database

From 6.0.15 on, one command does this step, the update scripts and the deploy, with a backup (a "caption") taken before the first write. Without --apply nothing is written:

./console exp:upgrade:status      # what is done and what is pending
./console exp:upgrade             # dry run: what every pending step would change
./console exp:upgrade --apply     # caption, then every pending step, then deploy and verify

See Upgrading with the console: exp:upgrade. To do the same by hand, apply the update files of the new code, each once, whole and in order.

From eZ Publish 5.4 or 5.90, first the file that brings the schema to Exponential 6.0.0:

mysql -u USER -p DATABASE < update/database/mysql/6.0/dbupdate-5.4.0-6.0.0.sql
psql -U USER DATABASE < update/database/postgresql/6.0/dbupdate-5.4-to-6.0.sql

From any 6.0.x (and after the file above), the file for the line:

mysql -u USER -p DATABASE < update/database/mysql/6.0/dbupdate-6.0.0-6.0.15.sql
psql -U USER DATABASE < update/database/postgresql/6.0/dbupdate-6.0.0-6.0.15.sql
sqlite3 var/storage/sqlite3/exponential.db < update/database/sqlite/6.0/dbupdate-6.0.0-6.0.15.sql

If your database already has a column a file adds, that one statement fails and names it; skip only that statement. A file that fails half way is never repaired by hand: restore the backup and apply it again from the start. Then run the one-time scripts of the 6.0.15 line:

php update/common/scripts/6.0/createaudittables.php
php update/common/scripts/6.0/movetrashrecords.php --remove-file
./console exp:user-login-check --allow-root-user                 # lists logins shared by two accounts
./console exp:user-login-check --fix-index --allow-root-user     # adds the unique index once there are none
./console exp:checkdbfiles --allow-root-user                     # the update files of your line are all present

5. Settings

Your settings in settings/override/ and settings/siteaccess/ keep their values. New settings of config.php-RECOMMENDED show up as "(not set)" in ./console exp:config:list; set the ones you want with ./console exp:config:set <NAME> <value> --apply. Read the checklist of each period you pass: accounts without an ezuser_setting row cannot sign in (August 2026), overrides follow Priority (July 2026), and security headers, HttpOnly and SameSite session cookies and a stricter upload check are on by default (September and October 2026). If WebDAV or SOAP is on, their entry scripts are index_webdav.php and index_soap.php since 6.0.15; change the virtual host and the rewrite rules. The details are in Upgrading, part C3.

6. Extensions

Update the extensions you installed with Composer one at a time, then check that every class still loads under your PHP:

php bin/php/ezpgenerateautoloads.php -e
./console exp:checkclasses --allow-root-user

exp:checkclasses reports every class PHP refuses to load, which is how a PHP 8 incompatibility in your own extension shows. Setup > Extensions lists each extension with its version. An extension can bring upgrade steps of its own: Upgrade steps for extensions.

7. Autoloads and caches

Rebuild the class map, clear the caches, then make the running PHP processes load the new code:

php bin/php/ezpgenerateautoloads.php -e
php bin/php/ezcache.php --clear-all --allow-root-user
systemctl reload <your-php-fpm-service>                      # Apache or nginx with PHP-FPM
./console exp:velocity deploy --allow-root-user                # Velocity: autoloads, caches, reload, restart, in order

Clear the content view cache after the reload (php bin/php/ezcache.php --clear-tag=content --allow-root-user): a page rendered by the old code between a clear and the reload would be cached again.

8. Verify

./console exp:checkclasses --allow-root-user
./console exp:info --json --no-logo > after.json      # compare with before.json
php bin/php/checkmanifest.php --all --extensions
php bin/php/maintenance.php off --allow-root-user

Then in the browser: the front page loads, you can log in to the administration, Setup > System information shows the new version, Setup > Upgrade check passes both checks (your own deliberate changes aside), and a test item you publish appears on the site. Read var/log/error.log for anything new.

9. Roll back

Decide before you start when you roll back: when the database step or the verification fails and the cause is not clear within the maintenance window. Put back, in this order:

1. The code. Git: check out the revision in backup-code-revision.txt, then composer install. Composer: put backup-composer.lock back as composer.lock, then composer install.
2. The database. Restore the dump of step 2 into an empty database. Never run the old code on the upgraded database.
3. The files in var/, only if the update scripts changed them, from backup-files-before-update.tar.gz.

Then repeat step 7 and step 8 with the old version. With exp:upgrade, ./console exp:upgrade:rollback lists the captions and restores one with --apply. A published release is never changed: the fix for a problem comes as the next version.

More

• Updating Exponential 6.0: this procedure in full, with a table of symptoms and fixes.
• Upgrading: from 4.x, 5.x or an earlier 6.0.x to today: every path, including LoveStack.
• Installing Exponential 6.0: a clean install of the same version, for a staging copy.
• Upgrading from 5.0 to 6.0: the 2024 notes for sites moving from a 4.7 or 5.0 legacy stack.
• Upgrading: every upgrade path and the pages of earlier versions.