Path / documentation / ez publish / upgrading / upgrading to 4.1 / 4.1.x to 4.1.y

Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

4.1.x to 4.1.y

This section describes how to upgrade your existing eZ Publish 4.1.x installation to version 4.1.y. If you are upgrading from a version prior to eZ Publish 4.1.0, refer to the "Upgrading from 4.0.x to 4.1.y" section for upgrade instructions.

In order to benefit from the latest bug fixes, you should upgrade directly to the latest stable release in the 4.1 branch (4.1.2 at the time of writing). Refer to the changelogs and security advisories for more information about the issues that were fixed in the latest releases.

Important upgrade notes:

  • "updateimagesystem.php" needs to be run before the "dbupdate" scripts, otherwise the tables being upgraded will be removed.

Please make a backup of your files and your database before proceeding. The procedure for upgrading directly from version 4.1.x to 4.1.y consists of the following steps:

  1. Check eZ Components version
  2. Update distribution files
  3. Transfer custom extensions
  4. Check updateimagesystem.php
  5. Upgrade database
  6. Regenerate autoload data for extensions
  7. Run system upgrade scripts
  8. Run eZ OE update script
  9. Clear caches

Step 1: Check the eZ Components 2008.2.x requirements

With eZ Publish 4.1.1 and later, eZ Components 2008.2.2 is the minimum version required. If you installed a previous version with PEAR, please upgrade to version 2008.2.2. For more information about installing eZ Components see also

Step 2: Updating the distribution files

The easiest way to upgrade the distribution files is to unpack eZ Publish 4.1.1 to a separate directory and then copy the directories that contain site-specific files from the existing installation. Make sure that you copy the following directories:

  • design/example
  • design/example_admin
  • var
  • settings/siteaccess
  • settings/override

Replace " example" and " example_admin" with the actual names of your siteaccesses.

Step 3: Custom extensions

If you are using custom extensions, the sub directories inside the "extension" directory will also have to be copied. However, make sure that you do not overwrite any extensions that come with eZ Publish (currently "ezoe", "ezodf"). Note that upgrading the distribution files will overwrite the autoload arrays for extensions. You will need to re-generate the autoload arrays for active extensions late. See below for dedicated upgrade instructions for ez flow and ez webin.

Note that ezdhtml is now replaced by ezoe, so you should not copy it over.

For eZ OE 5.0.x, you will need to have the following rewrite rule if using Virtual Hosts:

RewriteRule ^/var/[^/]+/cache/public/.* - [L]

For more detailed instructions, see the dedicated doc page:

Step 4: updateimagesystem.php

(If your upgrading from 4.1.0 and not directly from 4.0.x) First of all, if you don't have image data from before version 3.3 of eZ Publish, you don't have to do anything, you can skip running the "updateimagesystem.php" script

If you do have old data or you suspect you might (installation is based on eZ Publish < 3.3), which you want to upgrade, then you have to import the tables ezimage and ezimagevariation from a database backup, as these tables were unfortunately removed in the dbupdate scripts of 4.1.0. After the tables have been restored, the updateimagesystem.php script needs to be run.

Step 5: Upgrading the database

The update script for the database is located in:

<eZP root>/update/database/<mysql|postgresql>/4.1/dbupdate-4.1.x-to-4.1.y.sql

You can run this with the appropriate command line tool or application

Step 6: Regenerate the autoload array for extensions

The autoload system has also some changes, for example the autoload array for extensions is now placed in var/autoload of your eZ Publish installation.

To regenerate the autoload array, execute the following script:

php bin/php/ezpgenerateautoloads.php --extension

Step 7: Running the system upgrade scripts

The update scripts are located in:

<eZP root>/update/common/scripts/4.1

Please note, that if these scripts were executed as part of the initial upgrade in 4.1.0, they do not have to be executed again this time.

  • addlockstategroup.php (Used for creating locked states, part of the object states functionality. Updated in 4.1.1)
  • fixclassremoteid.php (Fixing remote IDs of classes. Updated in 4.1.2 for PostgreSQL compatibility.)
  • fixobjectremoteid.php (Fixes non-unique usage of content object remote IDs. Updated in 4.1.2 for PostgreSQL compatibility.)
  • correctxmlalign.php: after upgrading to 4.1 the default alignment for embedded images in ezxmltext datatype was removed, this script will allow you to have the correct xmlalignment.

Step 8: Run the eZ OE upgrade database script

(If you upgrade ezoe from 5.0.0 or earlier beta versions of the 5.0.x version) One of the bugs ( #14670) fixed in OE 5.0.1 caused object relations to be stored with wrong relation type id, so they where not removed as relation when you removed them from editor area (ezxmltext). In order to fix the problem on existing relations created with OE 5.0.0 (also affected all prior beta- and rc-releases), apply the following:

<eZP root>/extension/ezoe/update/database/5.0/dbupdate-5.0.0-to-5.0.1.sql

Step 9: Clearing the caches

Whenever an eZ Publish solution is upgraded, all caches must be cleared in a proper way. This should be done from within a system shell:

Navigate into the eZ Publish 4.0.y directory.
Run the script using the following shell command:

php bin/php/ezcache.php --clear-all --purge

Ole Marius Smestad (26/05/2009 2:30 pm)

Geir Arne Waaler (01/06/2011 11:11 am)

Ole Marius Smestad, André R., Ester Heylen, Geir Arne Waaler


  • Rewrite rule wrong upgrade page?

    The rewrite rule that needs to be added, from "Step 3: Custom extensions", doesn't that instruction belong on the 4.0 to 4.1 upgrade page instead of here?