17. Migration reference #

This chapter is the reference appendix for the three migration chapters before it. It holds the tables that those chapters point to rather than repeat: every table of the Exponential 6.0 kernel schema with its purpose and its name in eZ Platform and Ibexa; every kernel datatype with the columns it stores its value in and the matching field type; the INI settings that have a YAML counterpart; template constructs next to their Twig equivalents; the legacy PHP classes next to the Public API services; password hash types, URL alias tables and image storage paths; every upgrade, repair and conversion script in the installation; a list of data checks to run before moving content; and a glossary of the names that changed between generations. The old product names (eZ Publish 4.x and 5.x, eZ Platform, Ibexa DXP) appear only where they identify the system a site comes from or goes to.

Contents · Previous: 16. Migrating from eZ Platform and Ibexa

Contents of this chapter #

• 17.1 How the tables were verified
• 17.2 Database schema reference
• 17.3 Datatypes and field types
• 17.4 Settings: INI and YAML
• 17.5 Templates: TPL and Twig
• 17.6 PHP API: legacy classes and Public API services
• 17.7 Passwords, URL aliases and image storage
• 17.8 Data checks before migrating
• 17.9 Migration and upgrade tooling
• 17.10 Glossary of renamed concepts
• References

How to use it: start from the chapter of your path (14 for 4.x, 15 for the 5.x stack, 16 for eZ Platform and Ibexa) and come here when a step needs a name. Before any move, run the checks of 17.8 on a copy of the database: they find the data the other side will refuse, while it is still cheap to fix. For a move to the platform the datatype table of 17.3 decides what has to be converted; for a move to Exponential the "Ibexa 4.6" and "Ibexa 5" columns of 17.2 tell you which of your tables Exponential reads and which it ignores.

17.1 How the tables were verified #

Every name in this chapter was checked against code or data, in one of these places:

The reference database (SQLite) was opened read-only and queried with SELECT statements only. Anything that could not be checked in one of those places is marked (not verified here).

Ibexa DXP 4.6 still uses the legacy table names (ezcontentobject, ezuser ...) and the legacy field type identifiers (ezstring, ezimage ...). The Ibexa 5 database renames both: tables become ibexa_* with some columns renamed, and field types become ibexa_*. Both columns are given below where they differ.

17.2 Database schema reference #

The Exponential 6.0 kernel schema has 128 tables: share/db_schema.dba, kernel/sql/mysql/kernel_schema.sql and kernel/sql/postgresql/kernel_schema.sql list the same 128. kernel/sql/sqlite/schema.sql has three more, which belong to extensions but are created up front for SQLite: ezgmaplocation (ezgmaplocation), ezstarrating and ezstarrating_data (ezstarrating). The cluster tables (ezdfsfile, ezdfsfile_cache) are in the separate kernel/sql/mysql/cluster_dfs_schema.sql.

Legend for the last two columns: the table's name in the Ibexa DXP 4.6 legacy storage schema and in the Ibexa 5 reference database; "same" means the same name; "—" means the table does not exist there.

Content repository #

Datatype storage #

Users, roles and sessions #

URLs and search #

Workflows, notifications and collaboration #

Shop #

Other kernel features #

Tables that exist only on the Symfony platform #

Extensions bring their own tables, which keep their names on both sides when the extension has a platform counterpart: eztags, eztags_keyword and eztags_attribute_link (eztags and the Netgen Tags bundle) are present under those names in the Ibexa 5 reference database, and so is sckenhancedselection (enhancedselection2). The ezm_block and ezm_pool tables of ezflow (extension/ezflow/sql/) have no counterpart; see the Page field type in 17.3.

17.3 Datatypes and field types #

The kernel registers 35 datatypes (settings/content.ini [DataTypeSettings] AvailableDataTypes[]). Each is implemented in kernel/classes/datatypes/<name>/<name>type.php, and the data_type_string below is that class's DATA_TYPE_STRING. The storage columns are those of ezcontentobject_attribute. The sort key is what sortKeyType() returns: int fills sort_key_int, string fills sort_key_string, and false fills neither (kernel/classes/ezcontentobjectattribute.php).

The Ibexa 4.6 identifier is the alias in ibexa/core's fieldtypes.yml (or the bundle named); "Null" means 4.6 registers the identifier with the Null field type, which loads the stored value without understanding it. The Ibexa 5 identifier is the one in the field type reference or, where marked, the one stored in the reference database.

Extension datatypes found in this installation:

Notes on the conversions the vendor documents #

• XmlText to RichText. The vendor's migration page lists XmlText as replaced by RichText and as not supported on the platform; content is converted with ezxmltext:convert-to-richtext from ezsystems/ezplatform-xmltext-fieldtype (options --dry-run, --export-dir, --export-dir-filter, --image-content-types, --concurrency). RichText validates more strictly than XmlText, so run the dry run first. No such converter exists in this repository, in either direction; Exponential renders the DocBook elements ezembed, para and literallayout when they occur in imported ezxmltext (kernel/classes/datatypes/ezxmltext/handlers/output/ezxhtmlxmloutput.php), which keeps such text readable but does not convert it. The element mapping for a conversion of your own is in 15.8 and 16.6.3.

• Custom tags. Custom tag attribute types of the online editor (extension/ezoe/design/standard/templates/ezoe/customattributes/) map to RichText custom tag attribute types as the vendor documents:

  ezoe attribute type	RichText type	Vendor note
  link	link	supported
  number, int	number
  checkbox	boolean
  select	choice
  text	string
  textarea, email, hidden, color, htmlsize, csssize, csssize4, cssborder	string	"use as workaround"

  The tags themselves are declared in settings/content.ini [CustomTagSettings] AvailableCustomTags[] (factbox, quote, strike, sub, sup by default) and in extensions' content.ini.append.php.

• Page (ezflow). Replaced by the Page field type of the commercial editions; the open-source platform has no target. The vendor's ezflow:migrate command belongs to those editions.

• Star rating (ezsrrating). Listed by the vendor as unsupported: implement it or remove it from every class.

• Custom datatypes. Rewrite them as field types, or register the Null field type for their identifier so the stored values load without errors. Ibexa 4.6 already does this for the identifiers marked Null above.

17.4 Settings: INI and YAML #

Only pairs that can be shown to describe the same thing are listed. The YAML keys were checked against the generated configuration reference and the ibexa.yaml files of the Ibexa 5 reference installation; the database and file pairs are also the ones the legacy bridge maps automatically (doc/eng-us/specifications/6.0/legacy-bridge-bundle.md). <scope> is a siteaccess, a siteaccess group or default, under ibexa.system.

Siteaccesses, languages and design #

Database, files and clustering #

Users, sessions, URLs, caches and search #

Settings without a platform counterpart include site.ini [UserSettings] HashType and UpdateHash (the platform stores the hash type per user, see 17.7), [TemplateSettings] (template compilation), [SiteAccessSettings] RequireUserLogin, and every shop, workflow and notification setting.

17.5 Templates: TPL and Twig #

The TPL constructs below are defined in lib/eztemplate/classes/eztemplateautoload.php (language functions) and kernel/common/eztemplateautoload.php (kernel operators and functions). The Twig names are those of Ibexa 4.6 and 5, as used in the reference installation's templates; eZ Platform used the same names with an ez_ prefix (ez_render_field, ez_path ...), which Ibexa 4.6 still accepts.

override.ini and content_view express the same rule in two forms:

# settings/siteaccess/site/override.ini.append.php
[full_article]
Source=node/view/full.tpl
MatchFile=full/article.tpl
Subdir=templates
Match[class_identifier]=article

ibexa:
    system:
        site_group:
            content_view:
                full:
                    article:
                        template: '@ibexadesign/full/article.html.twig'
                        match:
                            Identifier\ContentType: article

The legacy match keys for node views are set in kernel/classes/eznodeviewfunctions.php (class_identifier, node, parent_node, section, section_identifier, depth, url_alias, state_identifier, parent_class_identifier, remote_id, node_remote_id, among others). The platform matchers with the same meaning (classes in Ibexa\Core\MVC\Symfony\Matcher\ContentBased, Ibexa 4.6):

17.6 PHP API: legacy classes and Public API services #

The legacy methods are in kernel/classes/ unless noted; the services are the interfaces in Ibexa\Contracts\Core\Repository (Ibexa 4.6, ibexa/core v4.6.28; on eZ Platform the namespace was eZ\Publish\API\Repository). Platform calls run as the current user set on PermissionResolver, where legacy code mostly ran with the logged-in user's rights and skipped checks in scripts.

eZContentObject and ContentService #

The legacy class has no publish() method; publishing goes through the publish operation or eZContentFunctions.

eZContentObjectTreeNode and LocationService #

eZUser and UserService #

eZContentClass and ContentTypeService #

Search, URL aliases, roles and the rest #

17.7 Passwords, URL aliases and image storage #

Password hash types #

ezuser.password_hash_type holds one of the constants of eZUser (kernel/classes/datatypes/ezuser/ezuser.php); eZUser::createHash() computes each one:

Ibexa 4.6 supports only 6 and 7 (SUPPORTED_PASSWORD_HASHES); Ibexa 5 adds 256. ezsystems/ezpublish-kernel 7.5 (eZ Platform 2.5) still declared 1, 2, 3, 5, 6 and 7, the MD5 and plain text types deprecated since kernel 6.13. All users in the Ibexa 5 reference database have type 7.

Exponential re-hashes on sign-in: with site.ini [UserSettings] UpdateHash=true (the default) and HashType=php_default (the default), eZUser::_loginUser() replaces any other stored type with a type 7 hash after a successful password check, updates password_hash and password_hash_type, and clears the user's cache. Users who have signed in since the site came to Exponential therefore already have a hash the platform accepts. To list the rest before migrating:

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

Accounts still on types 0 to 5 cannot sign in on the platform; they need a password reset there. ezuser.password_hash is VARCHAR(255) in the Exponential schema (kernel/sql/mysql/kernel_schema.sql), as on the platform, so bcrypt and Argon2 hashes fit.

URL alias tables #

The platform tables have the same columns under the same names (Ibexa 4.6) or ibexa_url_alias_ml, ibexa_url_alias_ml_incr and ibexa_url_wildcard (Ibexa 5), so aliases move with the data. They are regenerated afterwards with ibexa:urls:regenerate-aliases (exponential:urls:regenerate-aliases on Exponential Platform v5, which registers no ibexa: alias). The slug transformation must match: Exponential's default is urlalias ([URLTranslator] TransformationGroup), the Ibexa 5 reference installation uses urlalias_lowercase.

Image and file storage paths #

The vendor's instructions copy <old root>/web/var[/<site>]/storage to the same place in the new installation; image paths stored in the XML and in ezimagefile must then point to files that exist, which the checks in 17.8 find.

17.8 Data checks before migrating #

The vendor lists problems that appear after a migration. Each can be looked for in the Exponential database first. The SQL runs on MySQL, PostgreSQL and SQLite; run it on a copy.

The platform command names are those the vendor documents; their prefix changes between platform versions.

17.9 Migration and upgrade tooling #

Every bin/php/<name>.php is also ./console exp:<name>; the code of most of them is in kernel/private/classes/commands/. The standard options (-s/--siteaccess, -q, -v, -d, --allow-root-user) apply to all eZScript-based scripts. Chapter 11 explains the order to run them in.

Database update files #

update/database/<engine>/<version>/dbupdate-<from>-to-<to>.sql, for mysql, postgresql and sqlite. MySQL and PostgreSQL carry the chain from 4.0/dbupdate-3.10.0-to-4.0.0.sql through the 5.x steps (with unstable/ alpha, beta and rc steps for 4.0 to 5.0, and dbupdate-cluster-* files for the MySQL cluster at 4.3, 4.7, 5.2 and 5.4), then the 6.0 directory with the step from 5.4 (dbupdate-5.4.0-6.0.0.sql on MySQL, dbupdate-5.4-to-6.0.sql on PostgreSQL) and dbupdate-6.0.0-6.0.15.sql. SQLite has only 6.0/dbupdate-6.0.0-6.0.15.sql. Every MySQL file opens with SET default_storage_engine=InnoDB; (accepted by MySQL from 5.5.3 and by MariaDB); copies from before October 2026 said SET storage_engine, which current servers reject.

The 6.12/, 7.2/ (PostgreSQL only) and 7.3/ directories come from the upstream legacy line of 2016 to 2018 and are numbered after the Symfony kernel version they ran beside; never apply them as files. Their three schema changes (ezuser.password_hash widened to 255, the PostgreSQL sequences renamed to <table>_<column>_seq, ezcontentobject_trash.trashed) are made by the 5.4 to 6.0.0 file and again by the 6.0.0 to 6.0.15 file, each only where the database lacks it (11.3). Oracle has no 6.0 file: run the password_hash and trashed statements of 11.5 by hand. php bin/php/console exp:checkdbfiles --no-verify-branches checks that the tree is complete (table below).

update/common/scripts #

bin/php: schema, data and conversion #

Extension scripts: extension/eztags/bin/php/convertezkeyword.php moves ezkeyword attributes to eztags (--from-attr-id, --to-attr-id, --parent-tag-id); extension/enhancedselection2/bin/php/migrate_to_database.php and updateenhancedselection.php update enhanced selection storage.

bin/php: checks after an upgrade #

Shell helpers in bin/shell/: checkdbschema.sh, checkdbupdate.sh (--check-stable, --check-previous), verifyfiles.sh (--quiet) and generatefilelist.sh. In the admin, Setup, Upgrade check runs the same file check against share/filelist.md5 and compares the live schema with share/db_schema.dba merged with the active extensions' schemas (kernel/private/classes/views/setup/systemupgrade.php).

Moving to or from the platform #

This repository has no data converter to or from eZ Platform or Ibexa. The legacy bridge runs the Exponential kernel inside a platform installation on a shared database (branches for eZ Platform 2.5, Platform 3.3, Ibexa 4.6 and Platform 5), with the console commands exponential:legacy:init, configure, install-extensions, symlink, assets-install and script on the 3.x line from v3.0.0.30, the 4.x line from v4.0.0.2 and every 5.x tag, where the old ezpublish:* names remain as deprecated aliases. The 2.5 line (master, v2.1.10 to v2.1.12) and the earlier 3.x and 4.x tags know only the old names (ezpublish:legacy:init ...). On the platform side, the vendor documents ezxmltext:convert-to-richtext, ibexa:urls:regenerate-aliases, ezplatform:images:normalize-path and the ezpublish:update:legacy_storage_* commands listed in 17.8.

17.10 Glossary of renamed concepts #

References #

In this repository:

• 11. Upgrading: the order to run the update files and scripts in.
• Upgrading, Content model and editing, Templates and design, Operating a site.
• Legacy bridge, legacy bridge bundle specification, platform package map, platform site bundles, platform package forks and command renames.
• HTTP caching, file consistency check, audit trail, glossary.
• Code: share/db_schema.dba, kernel/sql/, kernel/classes/datatypes/, kernel/classes/datatypes/ezuser/ezuser.php, kernel/classes/ezcontentobjecttreenode.php, kernel/classes/datatypes/ezimage/ezimagealiashandler.php, lib/eztemplate/classes/eztemplateautoload.php, kernel/common/eztemplateautoload.php, settings/site.ini, settings/image.ini, settings/file.ini, settings/httpcache.ini, update/, bin/php/.

External:

• Vendor migration pages: Migrate from eZ Publish, Migrate from eZ Publish Platform, Common migration issues, Migrating from eZ Publish (eZ Platform 2.5 version) (the 1.13 version of the page is no longer published; its old address redirects to the current page).
• Field types: field type reference, Image, User, Null, MapLocation, Matrix.
• Source: ezsystems/ezpublish-legacy, ezsystems/ezpublish-kernel (User hash constants in 7.5), ezsystems/ezplatform-xmltext-fieldtype, ezsystems/LegacyBridge, ibexa/core.
• PHP: password_hash, password_verify.
• Symfony and Twig: Configuration, Doctrine DBAL connection URLs, Mailer DSN, ESI, Twig for template designers, Twig include.

Contents · Previous: 16. Migrating from eZ Platform and Ibexa