14. Migrating from the 4.x line #

This chapter moves a site that still runs eZ Publish 3.10, 4.0 to 4.7 or an early 5.x legacy kernel on PHP 5 to Exponential 6.0 on PHP 8. Chapter 11 lists the update chain; this chapter is the practical side of walking it from that far back. It covers what stays the same and what does not, how to take stock of the old site, a staging plan, the database runbook in the order that works with today's code (which update file, which repair script, which preflight query, per database engine), the files, the settings, the designs and templates, porting your own extensions from PHP 5 to PHP 8 with before and after code, passwords, search, checking the content afterwards, the problems people actually meet, a rollback plan and a checklist. Every command, path and setting in it was checked against the code of this repository; where the vendor's own upgrade pages for 4.0 to 4.7 say something else, the difference is pointed out.

Contents · Previous: 13. Security hardening for production · Next: 15. Migrating from the 5.x legacy stack

14.1 What changes, and what does not #

Exponential 6.0 is the same legacy kernel, carried forward. That decides the shape of the whole migration.

What stays the same, so you do not have to convert it:

What does change: PHP 5 to PHP 8 (your own PHP code is the largest piece of work), eZ Components replaced by Zeta Components installed by Composer (since 6.0.15 their fork, the expcomponents), the cluster handlers that stored files in the database, YUI (gone), jQuery (4.0.0), the online editor (TinyMCE 3 by default, TinyMCE 8 optional), several rewrite rules and a stricter security baseline. All of it is below.

Compared with the vendor's migration to its newer platform #

The vendor documented a migration from eZ Publish to its Symfony-based successor (Migrating from eZ Publish). That path is a different product and most of its work does not apply here:

14.2 Plan the migration on a staging copy #

Never migrate the live installation in place. Build the new site next to the old one, rehearse on a copy of the production database until the run is boring, then repeat it once against a fresh copy taken while the old site is in maintenance.

1. Freeze the old code. Note the exact old version (14.3), the list of active extensions and every file you changed in the kernel. Kernel changes are not carried over; they have to become extensions or overrides.
2. Staging server. PHP 8.0 to 8.5 (Exponential Velocity included), the database engine you will use in production, and the requirements of chapter 2.
3. New code. Get Exponential as in chapter 3. Do not run an installer against the old database: the setup wizard, the kickstarter and exp:install create a new database (11.1).
4. Rehearse. Restore the production dump on staging, run the database runbook (14.5), move the files (14.6), the settings (14.7), the designs (14.8) and the extensions (14.9), then verify (14.12). Write down every command and how long it took.
5. Fix and repeat until the rehearsal runs from top to bottom with no manual repair.
6. Cut over. Old site in maintenance, fresh dump, the same runbook, verification, DNS or proxy switch. Keep the old site and its database untouched for the rollback (14.14).

Three tracks can be worked in parallel by different people, because they only meet at the end: the database (14.5), the files and settings (14.6, 14.7), and the code (14.8, 14.9).

14.3 Take stock of the old site #

Run these on a copy of the old database; they only read.

Which version. The rows ezpublish-version and ezpublish-release of ezsite_data tell where the chain starts (the query is in 11.2). The update files 5.1 to 5.4 write 5.1.0alpha1 to 5.4.0alpha1 into that row; that is how they were shipped, not a sign of a failed step.

Which datatypes are in use. Anything that is not a kernel datatype comes from an extension you must port or install:

SELECT data_type_string, COUNT(*) FROM ezcontentclass_attribute
 WHERE version = 0 GROUP BY data_type_string ORDER BY 2 DESC;

Which password hash types are stored (see 14.10):

SELECT password_hash_type, COUNT(*) FROM ezuser GROUP BY password_hash_type;

Charset and table type (MySQL). The new code connects with [DatabaseSettings] Charset=utf-8, which the MySQL driver maps to MySQL's utf8 (lib/ezdb/classes/ezmysqlcharset.php). A database that is still latin1 or mixed must be converted (14.5.2).

SHOW CREATE DATABASE your_database;
SELECT table_name, engine, table_collation FROM information_schema.tables
 WHERE table_schema = 'your_database' ORDER BY engine, table_collation;

or, with the new code already pointed at the database, php bin/php/ezconvertmysqltabletype.php --list.

Cluster mode. Look in the old settings/override/file.ini.append.php for [ClusteringSettings] FileHandler. eZFSFileHandler (plain files) and eZDFSFileHandler (files on NFS, metadata in a database) exist in Exponential 6.0. eZDBFileHandler (files stored inside the database, table ezdbfile) and eZFS2FileHandler do not: they were removed in January 2013 (EZP-20288, "eZDB & eZFS2 Cluster removed in favor of eZDFS"). See 14.4.

Search engine. [SearchSettings] SearchEngine in the old site.ini overrides: eZSearchEngine is the built-in one; anything else is an extension such as eZ Find (14.11).

Size. These numbers drive how long each step takes (14.15):

SELECT COUNT(*) FROM ezcontentobject;
SELECT COUNT(*) FROM ezcontentobject_attribute;
SELECT COUNT(*) FROM ezcontentobject_tree;
SELECT COUNT(*) FROM ezurlalias_ml;
SELECT COUNT(*) FROM ezimagefile;

and the size of var/ (or of the DFS mount) on disk.

14.4 Prepare the old installation #

Do these on the old site while it still runs its old code, before you take the dump you migrate.

• Check consistency with the old admin. The vendor's Backup and consistency checks describe Setup > Upgrade check with Check file consistency and Check database consistency. The same two buttons exist in Exponential 6.0 (design/admin/templates/setup/systemupgrade.tpl), so run them again after the migration and compare.
• Leave the database cluster. If the old site uses eZDBFileHandler, move the files out of the database with the old installation's own tools while it still runs, and switch it to eZFSFileHandler (or to DFS). Exponential 6.0 has no handler that can read ezdbfile, so it cannot do this step for you.
• Optional clean-ups that make the dump smaller: remove internal drafts (set content.ini [ContentSettings] InternalDraftsCleanUpLimit and InternalDraftsDuration low and run the internal_drafts_cleanup.php cron job), old archived versions, expired sessions. The same tools exist in Exponential afterwards: php runcronjobs.php --script=internal_drafts_cleanup.php, php bin/php/cleanupversions.php --apply, php update/common/scripts/cleanup.php session.
• Back up the database and the whole old directory, including var/. The commands are in 11.1. Restore the backup once on a scratch machine.
• Record what works: a list of URLs per siteaccess and their HTTP status, a few searches and their result counts, the number of users who signed in last month. That list is your verification script in 14.12.

14.5 The database, step by step #

14.5.1 Which starting points work #

14.5.2 Before the first file: charset and table type #

On MySQL, convert MyISAM tables to InnoDB and a non-UTF-8 database to UTF-8 first, as the vendor did in its 3.10 to 4.0 step. Both scripts are in Exponential 6.0 and read the connection from the site's settings:

php bin/php/ezconvertmysqltabletype.php --list
php bin/php/ezconvertmysqltabletype.php --newtype=InnoDB
php bin/php/ezconvertdbcharset.php --help
php bin/php/ezconvertdbcharset.php

• ezconvertmysqltabletype.php takes --host, --user, --password, --database, --list, --newtype and --usecopy.
• ezconvertdbcharset.php runs on MySQL, PostgreSQL and Oracle (it refuses other drivers). Its options: --collation (default utf8_general_ci), --iconv-character-set (for a charset that iconv and the database name differently, the script's own example is windows-1252 and iso-8859-1), --log-filename, and --extra-xml-attributes, --extra-xml-data, --extra-serialized-data for your own tables or datatypes that store XML or serialized PHP. Serialized PHP stores byte lengths, so a datatype of yours that keeps serialized data must be named there or it will not unserialize after the conversion.
• Keep the converted tables on MySQL's utf8 (3-byte), which is what the connection uses. MySQL 8 creates new tables with utf8mb4 unless the database default says otherwise, and the update files create tables without naming a charset; set the database default to the same charset as the converted tables before you run them, so that old and new tables can be joined: ALTER DATABASE your_database CHARACTER SET utf8 COLLATE utf8_general_ci;

On PostgreSQL the database encoding is fixed at creation; a database that is not UTF-8 is converted with ezconvertdbcharset.php as well, or dumped and restored into a new UTF-8 database.

14.5.3 Preflight queries #

Three statements of the old chain fail on data that older releases allowed. Run these before the chain; each must return no rows.

-- 4.1 adds UNIQUE INDEX ezcontentobject_remote_id (from 4.0.1)
SELECT remote_id, COUNT(*) FROM ezcontentobject
 WHERE remote_id IS NOT NULL GROUP BY remote_id HAVING COUNT(*) > 1;

-- 4.1 adds UNIQUE INDEX ezgeneral_digest_user_settings_address before it removes stale rows
SELECT address, COUNT(*) FROM ezgeneral_digest_user_settings
 GROUP BY address HAVING COUNT(*) > 1;

-- 6.0.15 and later refuse to sign in an account without a settings row
SELECT u.contentobject_id, u.login FROM ezuser u
 LEFT JOIN ezuser_setting s ON s.user_id = u.contentobject_id
 WHERE s.user_id IS NULL;

What to do when they return rows:

• Duplicate object remote ids. Run the 4.1 file without the line ALTER TABLE ezcontentobject ADD UNIQUE INDEX ezcontentobject_remote_id(remote_id);, finish the chain, run php update/common/scripts/4.1/fixobjectremoteid.php --mode=a (--mode=d asks per duplicate), then add the index with exactly that statement. The same family has fixclassremoteid.php and fixnoderemoteid.php.

• Duplicate digest addresses. Keep the oldest row of each address before the 4.1 file:

  -- MySQL
  DELETE d1 FROM ezgeneral_digest_user_settings d1
    JOIN ezgeneral_digest_user_settings d2 ON d1.address = d2.address AND d1.id > d2.id;
  -- PostgreSQL
  DELETE FROM ezgeneral_digest_user_settings a
   USING ezgeneral_digest_user_settings b WHERE a.address = b.address AND a.id > b.id;

  The 5.0 file later replaces the address by a user_id column with a unique index.

• Users without ezuser_setting. See 14.10.

14.5.4 Two phases: schema first, data repair second #

The PHP repair scripts in update/common/scripts/ run on the Exponential 6.0 kernel, and that kernel's persistent object definitions describe the current schema. For example eZNodeAssignment reads the priority and is_hidden columns that only the 5.2 file adds, so 4.3/updatenodeassignment.php cannot run against a 4.3 database with today's code. Therefore:

1. Phase A applies every SQL file from your version up to 6.0.15, in order, with nothing in between, except the one script that must see the old schema (updateimagesystem.php, below).
2. Phase B runs the repair scripts of every version you passed, in version order, against the finished schema.

This differs from the vendor's per-version pages, which ran each version's scripts right after its SQL file with the matching old code. With today's single code base the two-phase order is the one that works.

updateimagesystem.php converts ezimage attributes of sites created before 3.3 and needs the ezimage table, which the 4.1 file drops. Check whether you need it:

SELECT COUNT(*) FROM ezimage;

If it returns 0, skip it. If not, run php update/common/scripts/4.1/updateimagesystem.php before the 4.1 file, on the rehearsal copy first: it runs the 6.0 kernel against a 4.0 schema.

14.5.5 Phase A: the SQL files #

Apply each file once, whole, in this order, starting after your version. The file names are the same under update/database/mysql/ and update/database/postgresql/ up to 5.4.

The 5.4 file says of its date update: "Skip this if updating from 5.3.3 or higher as this should ideally not be applied twice." Coming from 4.x you are below 5.3.3, so apply it.

MySQL. Every old file from 4.0 to 5.4, and 6.0/dbupdate-5.4.0-6.0.0.sql, starts with SET default_storage_engine=InnoDB;, which every MySQL from 5.5.3 and MariaDB accept, so apply the files whole. Copies from before October 2026 started with SET storage_engine=...;, which MySQL 5.7.5 and later and MariaDB 12.0 and later reject; take the current files:

mysql -u USER -p DATABASE < update/database/mysql/4.1/dbupdate-4.0.0-to-4.1.0.sql

The mysql client stops at the first failing statement in this mode. If that happens, note the statement, restore the backup, fix the cause (usually a preflight case) and start again from the backup.

PostgreSQL. Stop at the first error, too:

psql -v ON_ERROR_STOP=1 -U USER -d DATABASE -f update/database/postgresql/4.1/dbupdate-4.0.0-to-4.1.0.sql

The pgcrypto extension (function digest) must exist in the database for 6.0 (11.3).

SQLite and MongoDB. There is no old chain for them: SQLite support begins with 6.0.1, MongoDB with 6.0.14. Migrate on MySQL or PostgreSQL; moving a finished site to another engine afterwards is a separate project (chapter 9).

Oracle. The ezoracle extension carries the kernel chain for Oracle up to 5.3 in extension/ezoracle/update/database/ (11.3). There is no Oracle file for 5.4 or 6.0: write the 5.4 changes from the MySQL file in Oracle syntax, then run by hand what the 6.0 files do on the other engines, at least ALTER TABLE ezuser MODIFY ( password_hash VARCHAR2(255) ); and, if the table lacks it, ALTER TABLE ezcontentobject_trash ADD ( trashed INTEGER DEFAULT 0 NOT NULL ); (11.5), then the columns and tables of the 6.0.15 file in Oracle syntax (the audit tables come from createaudittables.php, which works on Oracle). Rehearse this path twice as often as the others; it is the least travelled.

Check the tree before you start. php bin/php/console exp:checkdbfiles --no-verify-branches compares the update files with the upgrade path, every directory from 4.0 to 7.3 on every engine, and prints ! for a missing file and ? for one it does not expect. Silence means the tree is complete. Without --no-verify-branches it also tries to reach the retired SVN repository of the old vendor and reports one C line.

Patch-release markers. Some files contain blocks marked -- START: from 4.0.1 ... -- END: from 4.0.1 (also from 3.10.1, from 4.0.2, from 4.1.0, from 4.1.1, from 4.1.2, from 4.1.4). They hold the statements that a later patch release of the older line already shipped. If your database came through that patch release's own update (for example you ran 4.0.2 and applied its update), those statements were applied before and fail with "duplicate column" or "duplicate key". Make a copy of the file without the blocks your site already has and apply the copy. This is the "select the appropriate SQL for 4.1.1, 4.1.2, 4.1.3 or 4.1.4" note of the vendor's direct upgrade from 4.1 to 4.7. The vendor's 4.0 page also names a file dbupdate-4.0.0-to-4.0.1.sql; in this repository its statements are the from 4.0.1 block of the 4.1 file.

unstable/ directories hold the files of alphas, betas and release candidates. A site that ran a final release never applies them. A site that ran a pre-release must apply the remaining unstable/ files of that line up to the final release instead of the stable file.

Cluster files (MySQL only). The DFS metadata database is a separate database. Apply to it, at the same point in the chain:

14.5.6 Phase B: the repair scripts #

Run from the installation root, after phase A, the scripts of every version you passed, in this order. Start each with --help. Scripts that offer a dry run (--dry-run, or -n where it means "do not change") get one first.

The vendor's direct-upgrade page says to skip the 4.4 section identifier script "(bug in update script)" and use the 4.5 one; in this repository both files are the same.

14.6 Files: storage, images, binary files and the cluster #

• Copy var/ (or at least var/<VarDir>/storage/) from the old site. Keep [FileSettings] VarDir in settings/override/site.ini.append.php exactly as it was: the paths of every stored image and file in ezimagefile and in the ezimage XML start with it. A site whose VarDir changed during its life has images outside it; 5.1/fiximagesoutsidevardir.php fixes the references.
• Do not copy caches. Leave out var/cache/, var/<VarDir>/cache/ and var/autoload/; the new code rebuilds them. The vendor's pages end every step with php bin/php/ezcache.php --clear-all --purge and a manual check of var/cache/ and var/<siteaccess>/cache/; the same command works here (--purge removes the files physically).
• Image aliases are made on demand from the original image and the aliases of image.ini [AliasSettings] AliasList[] (reference, small, tiny, medium, large, rss by default). Carry over your own alias blocks from the old image.ini.append.php and clear the alias cache (php bin/php/ezcache.php --clear-id=imagealias); every alias is rebuilt the first time it is asked for. image.ini [ImageConverterSettings] ImageConverters[] lists GD and ImageMagick; [ImageMagick] Executable=convert, ExecutablePath empty.
• File permissions. The vendor's pages used chmod -R a+rwx design extension settings var. Do not: the user that runs PHP needs to write var/ (and settings/override/ only if the admin edits settings); see chapter 8 and chapter 13.

The cluster #

index_cluster.php serves cluster files. It reads config.php and config.cluster.php and expects the constants CLUSTER_STORAGE_BACKEND (for example dfsmysqli), CLUSTER_STORAGE_HOST, CLUSTER_STORAGE_PORT, CLUSTER_STORAGE_USER, CLUSTER_STORAGE_PASS and CLUSTER_STORAGE_DB (config.php-RECOMMENDED shows them). The 4.5 and 4.6 pages of the vendor set define( 'STORAGE_BACKEND', 'dfsmysqli' ) inside index_cluster.php; that name is not read any more, and the old index_cluster_* and index_image_* files are to be removed from the document root (4.7 notes). The tools for a DFS site: php bin/php/clusterize.php (-u moves files back to the plain file system), php bin/php/dfscleanup.php (consistency between ezdfsfile and the mount), php bin/php/clusterpurge.php --apply.

14.7 Settings and siteaccesses #

What to carry over #

Copy, from the old installation into the new one, only:

• settings/override/ (global overrides),
• settings/siteaccess/<name>/ for every siteaccess,
• config.php or config.cluster.php if the old site had them (compare with config.php-RECOMMENDED),

then go through them with the list below. Never copy the old settings/*.ini files over the new ones: the new defaults are part of the code. The vendor's pages said the same in their step 1 (copy settings/siteaccess, settings/override and the site's own design/<site> directories into the unpacked new release).

To compare a carried-over config.php with the template without an editor, run in the new root:

./console exp:setup:status                 # config.php: how many settings it sets, or that it does not compile
./console exp:setup:config                 # the diff between config.php and config.php-RECOMMENDED (changes nothing)
./console exp:config:list                  # every documented setting: the value config.php has, or (not set)
./console exp:config:set CLUSTER_STORAGE_BACKEND dfsmysqli --apply    # set or correct one value, backup first

A setting the old file defines inside an if is reported as conditional and left to you. Without an old config.php, ./console exp:setup:config --apply creates one from the template; for .htaccess, take the new .htaccess_root with ./console exp:setup:htaccess --apply rather than the old site's copy. See Setting up .htaccess and config.php from the console.

Settings to change #

Then rebuild the INI cache and check each siteaccess:

php bin/php/ezcache.php --clear-tag=ini
php bin/php/ezpgenerateautoloads.php -e

Rewrite rules #

The vendor's 4.x pages added and removed rewrite rules release by release (index_ajax.php for ezjscore calls, var/([^/]+/)?cache/(texttoimage|public), the extension design directories). index_ajax.php no longer exists. Do not carry the old rules over: take the rules of chapter 8 for your web server, which list exactly what may be served, and add only rules your own extensions need.

Siteaccesses #

Siteaccess matching ([SiteAccessSettings] MatchOrder, HostMatchMapItems[], URIMatch...) is unchanged; copy it. Check each siteaccess after the move:

php bin/php/eztemplatecheck.php -s<siteaccess>

and open its front page. The editor siteaccess and the newer admin designs are additions you can make afterwards (10. After installing).

14.8 Designs, templates and JavaScript #

Your designs. Copy your own design/<name>/ directories, or better, move them into a design extension (extension/<yours>/design/<name>/ with design.ini.append.php [ExtensionSettings] DesignExtensions[]), so that updates of Exponential never touch them. Overriding templates live in design/<name>/override/templates/, as the vendor's 4.0 page required.

Do not edit packaged extensions. ezwebin, ezflow, ezoe, ezjscore and the other extensions of composer.json are replaced on every update. Changes you made inside them on the old site must move into your own design extension as overrides.

Check the syntax of every template of a siteaccess, or of a directory:

php bin/php/eztemplatecheck.php -s<siteaccess>
php bin/php/eztemplatecheck.php extension/<yours>/design/

What behaves differently in templates:

eZ Webin and eZ Flow. In 4.x they were upgraded with bin/php/ezwebinupgrade.php and bin/php/ezflowupgrade.php against the vendor's package server. Here the extension code arrives with Composer (se7enxweb/ezwebin, se7enxweb/ezflow); the two scripts still exist for the installed site packages (11.6, step 4). The vendor's direct-upgrade page adds an index for eZ Flow sites coming from 4.1 or 4.2: ALTER TABLE ezm_pool ADD INDEX ezm_pool__block_id__ts_hidden (block_id, ts_hidden); the current ezflow schema (extension/ezflow/sql/mysql/mysql.sql) has that index, so add it if your database lacks it.

14.9 Porting your own extensions from PHP 5 to PHP 8 #

This is the largest part of most migrations. Work through it on staging with debug output on.

The checklist #

1. Inventory your extensions: everything under extension/ that is not in composer.json.
2. Lint every PHP file with the PHP you will run: find extension/<yours> -name '*.php' -print0 | xargs -0 -n1 php -l. A parse error here stops the whole site, not only the extension.
3. Regenerate the autoload array (php bin/php/ezpgenerateautoloads.php -e) and load every class: php bin/php/console exp:checkclasses reports each class PHP refuses to load (signature conflicts, missing parents, removed functions at class level). --kernel includes the kernel.
4. Check characters around the PHP tags: php bin/php/ezcheckphptag.php extension/<yours>.
5. Fix the PHP 8 breaks below, then the deprecations shown in the debug output.
6. Templates and settings as in 14.7 and 14.8.
7. Give the extension a version: ezinfo.php and extension.xml, shown on Setup > Extensions.

Autoloading and constants #

4.0 replaced the include lists with one class per file and generated autoload arrays. In Exponential 6.0 the kernel array is autoload/ezp_kernel.php; the extension, kernel-override and test arrays are generated into var/autoload/ezp_extension.php, ezp_override.php and ezp_tests.php by ezpgenerateautoloads.php (-e extensions, -k kernel, -o kernel overrides, -s tests, --exclude=<dir>, -n dry run). A kernel override array is used only when config.php defines EZP_AUTOLOAD_ALLOW_KERNEL_OVERRIDE as true. Registration uses spl_autoload_register(); a function __autoload() in your code is a fatal error since PHP 8.0.

The global constants of 3.x were replaced by class constants in 4.0 (the vendor's 4.0 notes use EZ_CONTENT_OBJECT_STATUS_DRAFT as the example) and the old names are not defined:

// before (3.x)
if ( $object->attribute( 'status' ) == EZ_CONTENT_OBJECT_STATUS_DRAFT )
// after
if ( $object->attribute( 'status' ) == eZContentObject::STATUS_DRAFT )

Constructors named after the class #

Since PHP 8.0 a method with the class's name is not a constructor. For a datatype this is fatal: new falls through to eZDataType::__construct( $dataTypeString, $name, ... ), whose first two parameters are required.

// before (PHP 5)
class myRatingType extends eZDataType
{
    function myRatingType()
    {
        $this->eZDataType( 'myrating', 'Rating' );
    }
}

// after
class myRatingType extends eZDataType
{
    const DATA_TYPE_STRING = 'myrating';

    public function __construct()
    {
        parent::__construct( self::DATA_TYPE_STRING, 'Rating' );
    }
}
eZDataType::register( myRatingType::DATA_TYPE_STRING, 'myRatingType' );

The kernel keeps courtesy methods with the old names (eZDataType::eZDataType(), eZPersistentObject::eZPersistentObject(), eZWorkflowType::eZWorkflowType(), eZWorkflowEventType::eZWorkflowEventType()), so $this->eZDataType( ... ) inside your own __construct() still works; your class's own old-style constructor is what no longer runs. See also 5.90 and PHP 7.

Signatures that must match the parent #

PHP 8 checks every overriding method against its parent when the class loads. By-reference parameters, a different number of parameters or a different default break the class. The kernel's eZDataType methods take objects by value:

// before: fatal on PHP 8 ("Declaration ... must be compatible with ...")
function onPublish( &$contentObjectAttribute, &$contentObject, &$publishedNodes ) { ... }

// after: as in kernel/classes/ezdatatype.php
function onPublish( $contentObjectAttribute, $contentObject, $publishedNodes ) { ... }

Exponential's own extensions had exactly this (syndication's onPublish(), ezstarrating's makeObjectsArray()), see PHP 8.0 support.

Functions and syntax removed from PHP #

Exponential fixed the same in its own extensions: birthday used each(), enhancedezbinaryfile used split(), the OAuth module and swark called implode() with swapped arguments.

Deprecations to clear (not fatal, but noisy and next in line) #

// Implicitly nullable parameter (deprecated in 8.4)
function load( eZContentObject $object = null )      // before
function load( ?eZContentObject $object = null )     // after

// Dynamic properties (deprecated in 8.2): declare them
class myHelper
{
    public $cache = array();                          // declared, no warning
}

// null passed to string functions (deprecated in 8.1)
$length = strlen( $value );                           // before
$length = strlen( $value ?? '' );                     // after

// count() on something that may not be countable (warning since 7.2, TypeError since 8.0)
$n = count( $list );                                  // before
$n = is_countable( $list ) ? count( $list ) : 0;      // after

// "${var}" interpolation (deprecated in 8.2)
$s = "Node ${nodeID}";                                // before
$s = "Node {$nodeID}";                                // after

// Methods implementing Iterator, ArrayAccess, Countable (deprecated return types in 8.1)
#[\ReturnTypeWillChange]
public function current() { ... }

utf8_encode() and utf8_decode() are deprecated since 8.2 (mb_convert_encoding()); calling a non-static method statically is an Error since 8.0; comparisons between numbers and non-numeric strings changed in 8.0 (0 == 'a' is false). eZPersistentObject already carries #[AllowDynamicProperties] and stores undeclared fields itself, so subclasses do not warn; your other classes must declare their properties. The kernel's own sequence of PHP 8 changes, release by release, is in PHP 8 support.

php.ini #

eZ Components #

4.x needed eZ Components installed beside the code, at a minimum version per release (2008.2 for 4.1, 2009.1 for 4.2, 2009.2.1 for 4.3 and 4.4, ezcomponents-ezp45 to ezcomponents-ezp47 later). Exponential used their continuation, Zeta Components, installed by Composer (zetacomponents/* in composer.json) and loaded by Composer's class map. Since 6.0.15 it uses Exponential's own fork of them, the expcomponents (se7enxweb/expcomponents-*, Apache 2.0), which replace the zetacomponents/* names (Exponential Components). The class names (ezcMail, ezcConsoleInput ...) are the same in all three; remove any include path or ezc directory you set up for 4.x.

14.10 Users, passwords and sign-in #

Old hashes keep working and are upgraded at sign-in. ezuser.password_hash_type names the method of each stored hash (kernel/classes/datatypes/ezuser/ezuser.php):

With [UserSettings] UpdateHash=true (the default) a successful sign-in with an old hash stores a new one of HashType. Things to carry over and check:

• md5_site hashes contain [UserSettings] SiteName. That is a separate key from [SiteSettings] SiteName, and its default is ez.no. If the old site changed it, set the same value in settings/override/site.ini.append.php, or those users cannot sign in.
• mysql hashes are checked with PASSWORD(), which MySQL 8.0 removed. On MySQL 8, those accounts cannot sign in; reset their passwords (below) or have them use "forgot password".
• Accounts without an ezuser_setting row cannot sign in since August 2026: a missing row now counts as disabled. The old chain itself deletes orphaned rows (4.0 and 5.4 files) but never creates missing ones. Find them with the preflight query of 14.5.3 or the queries of the August 2026 security specification.
• The hash column must be wide before anyone signs in. A 4.x database has ezuser.password_hash varchar(50); the first sign-in rewrites the hash to a 60-character bcrypt hash. The 5.4 to 6.0.0 file widens the column to 255 (and the 6.0.0 to 6.0.15 file again, for older copies), so keep the site in maintenance until phase A is complete. If users signed in against a narrow column, the column refused the hash (strict SQL mode) or cut it, and those users cannot sign in again: widen the column, then reset their passwords. On Oracle widen it by hand (14.5.5).
• Passwords shorter than 10 characters keep working; the new minimum applies when a password is set.
• Reset a password from the command line: php bin/php/resetuserpassword.php -a admin -ap '<admin password>' -u <login> -p '<new password>'.

14.11 Search #

The built-in engine (site.ini [SearchSettings] SearchEngine=eZSearchEngine) is the default. Its tables are part of the update chain (the 5.4 file drops ezsearch_return_count), but rebuild the index after the migration rather than trust the old one:

php bin/php/updatesearchindex.php --clean

eZ Find (Solr) is suggested in composer.json as se7enxweb/ezfind; install it as a package and reindex with its own tools. settings/solr.ini and php bin/php/console exp:solr control a Solr server for this installation; it is off until [SolrSettings] Enabled=true. Relations are indexed one level deep since 2018 (relation indexing): search results that relied on relations of relations change.

14.12 Verify the content after the migration #

Run the checks of 11.7, and in addition:

1. Schema against the reference. share/db_schema.dba is the schema of the current release. Compare the migrated database with it; the exit code says whether they differ:

   php bin/php/ezsqldiff.php --type=mysql --user=USER --password=PASS share/db_schema.dba DATABASE

   (--type=postgresql on PostgreSQL). The output is the SQL that would turn the second argument (your database) into the first (the reference): a CREATE TABLE or ADD line names something a missed step should have made, a DROP TABLE line a table only your database has. Tables of your own extensions show up as such drops; anything else is a step that was missed. Read the output, do not run it: repair by restoring and running the missed step.

2. Counts against the old database. Run the size queries of 14.3 on the old and the migrated database. Objects, attributes and nodes must match exactly; ezurlalias_ml grows when aliases are rebuilt.

3. URL aliases. php bin/php/updateniceurls.php (with --update-nodes), then php bin/php/verify_aliases.php (--fix repairs what it can safely, --verbose explains).

4. Images and files. Open a page of each class with images; the alias is generated on the first request. The 5.1, 5.3 and 5.4 image scripts of phase B report broken references.

5. The admin's Upgrade check. Setup > Upgrade check, both buttons.

6. Every siteaccess: php bin/php/eztemplatecheck.php -s<siteaccess>, then the URL list you recorded in 14.4, comparing HTTP status codes.

7. Editing. Create, edit and publish an object of each class with ezxmltext, an image and a relation, in every language. Check that the object appears in search.

8. Users. Sign in as an editor whose hash is still an old type (14.10) and check that password_hash_type changed to 7 afterwards.

9. Cron jobs run without errors: php runcronjobs.php and php runcronjobs.php frequent (or the parts set in cronjob.ini), see chapter 10.

10. Logs. var/log/error.log and var/log/warning.log (and var/<VarDir>/log/) stay quiet while you click through the site.

14.13 Common issues #

The vendor lists the issues people met in its own migration (Common migration issues). Their Exponential counterparts first, then the ones specific to the legacy path:

More symptoms and fixes for running sites: chapter 12.

14.14 Rollback plan #

A migration is rolled back by not switching, never by undoing the migrated database.

• Until the switch: the old site keeps serving (in maintenance mode during the final run). Rollback is: take the old site out of maintenance (php bin/php/maintenance.php off on Exponential; on the old site, whatever it used).
• After the switch: keep the old server, its code and an untouched copy of its database for at least as long as it takes to be sure. Point DNS or the proxy back to it. Content created on the new site after the switch is not in the old database; for that reason keep editing frozen (or at least logged) for the first days, or plan to re-enter those changes.
• Never run an update file a second time to "repair" a half-done run; restore the dump taken before the run and start the runbook again.
• Keep the dumps: the old production dump, the migrated dump right after 14.12, and the var/ archive. With those three you can rebuild either side.

14.15 How long it takes #

The time depends far more on the size of a few tables than on the version you come from. Measure it in the rehearsal and plan the production window from the measurement, with a margin. What scales with what:

The database steps can run while the old site is still serving, on the rehearsal copy; only the final run needs the maintenance window. Reindexing can be finished after the switch if search may be incomplete for a while.

14.16 The vendor's upgrade pages, point by point #

The vendor documented each step of the 4.x line separately. Every point those pages make is covered above; this table says where, and how Exponential differs.

14.17 Migration checklist #

Before:

• To do: Old version, extensions, datatypes, hash types, charset, table types, cluster mode, search engine recorded (14.3)
• To do: Old site consistency checks run; database cluster left; optional clean-ups done (14.4)
• To do: Full backup of the old database and directory, restored once on a scratch machine
• To do: Staging server with PHP 8 and Exponential 6.0 code; no installer run against the old database (14.2)
• To do: URL list, search counts and sign-in figures recorded for comparison

Database (on staging, then for real):

• To do: Tables InnoDB, database UTF-8, database default charset set (14.5.2)
• To do: Preflight queries return no rows, or their fix is planned (14.5.3)
• To do: ezimage checked; updateimagesystem.php run before the 4.1 file if needed (14.5.4)
• To do: Phase A: every SQL file from your version to 6.0.15, in order, patch-release blocks handled, cluster files on the DFS database (14.5.5)
• To do: Phase B: repair scripts of every version passed, dry runs first (14.5.6)
• To do: createaudittables.php run; version row reads 6.0.15stable

Files and settings:

• To do: var/ storage copied, VarDir unchanged, caches not copied (14.6)
• To do: Cluster: DFS with the mysqli backend, CLUSTER_* constants (14.6)
• To do: settings/override/ and settings/siteaccess/ carried over and reviewed against 14.7
• To do: Rewrite rules taken from chapter 8

Code:

• To do: Designs moved to a design extension; nothing edited inside packaged extensions (14.8)
• To do: Templates checked with eztemplatecheck.php; YUI and old jQuery calls replaced
• To do: Own extensions linted, autoloads regenerated, exp:checkclasses clean, PHP 8 breaks and deprecations fixed (14.9)

After:

• To do: Users: ezuser_setting rows, [UserSettings] SiteName, mysql hashes handled (14.10)
• To do: Search index rebuilt (14.11)
• To do: Schema compared with share/db_schema.dba; counts compared; aliases verified; Upgrade check run (14.12)
• To do: Editing, publishing, sign-in, cron jobs and logs checked
• To do: Caches cleared after the PHP reload; old site and dumps kept for rollback (14.14)

References #

In this repository:

• 11. Upgrading: the update chain this chapter walks, the 6.0 steps and the verification commands; 12. Troubleshooting; 13. Security hardening; 2. Requirements; 8. Serving the site; 9. Databases.
• Upgrading guide.
• Release notes of the 4.x line: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7.
• Changelogs of the old line: 3.9 to 3.10, 3.10 to 4.0, 4.0 to 4.1, 4.1 to 4.2, 4.2 to 4.3, 4.3 to 4.4, 4.5 to 4.6, 4.6 to 4.7.
• 5.90 line: overview, PHP 7, password length, relation indexing.
• PHP 8: PHP 8 support, PHP 8.0 support.
• JavaScript and editor: YUI removed, jQuery 4 and YUI removal, TinyMCE 3 and TinyMCE 8 in ezoe.
• Extensions: extension loading order, additional extension directories, behaviour changes of the legacy extensions.
• The product is called Exponential, maintenance mode, file consistency check, audit, legacy bridge, security hardening August 2026.
• Code: update/database/, update/common/scripts/, bin/php/ezconvertdbcharset.php, bin/php/ezconvertmysqltabletype.php, bin/php/ezsqldiff.php, bin/php/updateniceurls.php, bin/php/verify_aliases.php, bin/php/ezpgenerateautoloads.php, bin/php/eztemplatecheck.php, bin/php/resetuserpassword.php, kernel/classes/datatypes/ezuser/ezuser.php, kernel/classes/ezdatatype.php, kernel/classes/ezpersistentobject.php, lib/ezdb/classes/ezmysqlcharset.php, index_cluster.php, config.php-RECOMMENDED, share/db_schema.dba.

The vendor's upgrade documentation for the 4.x line (archived copy of the former doc.ez.no pages):

• How to proceed, Backup and consistency checks, Direct upgrading, The system upgrade scripts.
• 4.0: important notes, 3.10 to 4.0, 4.0 to 4.1, 4.1 to 4.2, 4.2 to 4.3, 4.3 to 4.4, 4.4 to 4.5, 4.5 to 4.6, 4.6 to 4.7, direct 4.1 to 4.7.

The vendor's migration to its newer platform:

• Migrating from eZ Publish
• Common migration issues

PHP migration guides: 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5.

Code and packages:

• Exponential on GitHub: github.com/se7enxweb/exponential (releases).
• The original legacy kernel, as the historical source of the update files: github.com/ezsystems/ezpublish-legacy.
• Packagist: se7enxweb/exponential.
• MySQL: character sets; PostgreSQL: psql, pgcrypto.

Contents · Previous: 13. Security hardening for production · Next: 15. Migrating from the 5.x legacy stack