Path / documentation / ez publish / upgrading / upgrading to 4.2 / upgrading from 4.1.x to 4.2.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.

Upgrading from 4.1.x to 4.2.y

This section describes how to upgrade your existing eZ Publish 4.1.x installation to version 4.2. If you are upgrading from version earlier than 4.0.3, you first need to upgrade to 4.0.3 before you can upgrade to 4.2 (Refer to either "Upgrading from 3.10.x to 4.0.y" or "Upgrading from 4.0.x to 4.0.y" depending on which version you are currently running.)

The upgrade procedure described below is generic and does not cover any specific cases (for example, running eZ Publish in a clustered environment).

Make sure that you have a working backup of the site before you do the actual upgrade.

Important upgrade notes:

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

The procedure for upgrading directly from version 4.1.x to 4.2 consists of the following steps:

  1. Upgrading the distribution files to 4.2
  2. Upgrading custom extensions
  3. Updating image system
  4. Upgrading the database to 4.2
  5. Regenerate the autoload array for extensions
  6. Running the system upgrade scripts for versions from 4.0.x to 4.2
  7. Clearing the caches

Check for requirements

The eZ Components 2009.1 requirements

With eZ Publish 4.2, eZ Components 2009.1 is the minimum version required. If you installed a previous version with PEAR, please upgrade to version 2009.1. For more information also see

The PHP requirements

Although a PHP version 5.2.x is listed as required (with the exception of PHP 5.2.9 which has a serious regression in the array_unique() call), full PHP version 5.3 compatibility is also provided.

For more information regarding system requirements check out

Step 1: Upgrading the distribution files

The easiest way to upgrade the distribution files is to unpack eZ Publish 4.2 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 2: Custom extensions

If you are using custom extensions, the subdirectories 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, which currently are eZ Online Editor (5.0.4) and eZ (2.4.0). 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 later.

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.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:

The updated versions of eZ Flow and eZ Website Interface will also install the following extensions:

  • eZ Website Toolbar (separated from eZ Web site)
  • eZ JS Core (base library for client side Javascript and Ajax functions)
  • eZ Star Rating
  • eZ Google Maps Location

Step 3: updateimagesystem.php

This script is necessary to run if you have data of the 'ezimage' datatype, dating from before eZ Publish 3.3, in version 3.3 a new image system took over based on ezimagealiashandler.

If you are upgrading to the 4.2 series of eZ Publish for the first time, and the installation at hand has been running since prior to eZ Publish 3.3 then you need to run the updateimagesystem.php script before running any of the dbupdate scripts for version 4.2.

If the installation at hand is a new installation or based on any eZ Publish version since 3.3 then you can skip running the updateimagesystem.php script.

Step 4: Upgrading the database

The update script for the database is located in

<eZP root>/update/database/<mysql|postgresql>/4.2/dbupdate-4.1.0-to-4.2.0.sql

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

Step 5: Regenerate the autoload array for extensions

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

To regenerate the autoload array, execute the following script from

php bin/php/ezpgenerateautoloads.php --extension

 Step 6: Running the system upgrade scripts

Run the following two upgrade scripts:

The update script in <root of ez publish installation>/update/common/scripts/4.1 is:

  • correctxmlalign.php: after upgrading to 4.1 the default alignment for embedded images in ezxmltext datatype is removed, this script will allow you to have the correct xmlalignment.

The update script in <root of ez publish installation>/update/common/scripts/4.2 is:

  • fixorphanimages.php: this script will delete images from the storage directory that are no longer connected to any content object attribute

Step 7: 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:

  1. Navigate into the eZ Publish 4.2 directory.
  2. Run the script using the following shell command:

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

Purging ensures that the caches are physically removed. When the "--purge" parameter is not specified, the caches will be expired but not removed.

Sometimes the script is unable to clear all cache files because of restrictive file/directory permission settings. Make sure that all cache files have been cleared by inspecting the contents of the various cache sub-directories within the "var" directory (typically the "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are any cache files left, you need to remove them manually.

Upgrading eZ Flow and/or Website Interface separately

Step 1: Backup

Before you will start the Website Interface or eZ Flow upgrading process make sure that you have a backup of the existing website state including database, extensions, INI settings, etc. During the upgrade process existing eZ Flow and eZ Webin extensions will be removed and replaced with a new version. Website Interface and eZ Flow default content classes will be replaced as well. Upgrade script will also change some of the existing INI settings and add new ones which are required by latest version.

Step 2: eZ Flow upgrade

For information regarding upgrading to eZ Flow 2.0 please visit the following extension upgrading page.

To get more information about available upgrade options, execute ezflowupgrade.php script with –help parameter:

php bin/php/ezflowupgrade.php --help

 Step 3: Re-write rules

Users running their eZ Flow sites in VH mode should update their extension related re-write rules to the following:

Rewriterule ^/extension/[^/]+/design/[^/]+/(stylesheets|flash|images|lib|javascripts?)/.* - [L]

 Step 4: Website Interface upgrade

For more information regarding upgrading to eZ Webin 1.5 please visit the following extension upgrading page.

To get more information about available upgrade options, execute ezwebinupgrade.php script with –help parameter:

php bin/php/ezwebinupgrade.php --help

 Step 5: Regenerate the autoload array for extensions

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

To regenerate the autoload array, execute the following script from:

php bin/php/ezpgenerateautoloads.php --extension

 Step 6: Cache

Once the upgrade script is done, you need to clear the cache by executing following command from eZ Publish root folder:

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

Ester Heylen (24/09/2009 2:30 pm)

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

Ester Heylen, Geir Arne Waaler


  • eZ Flow and JS Core

    For those who have used eZ Flow outside of standard packages or any custom way - with new eZ Flow you will also require the JS core extension to active extensions.
  • migation to 4.2

    I ran through successfully the upgrade steps including ezwebin. However, my site is not working properly anymore. admin site shows "Click on icon to show the contextual menu" in the name of each sub-element of the site. Checking the database in the administration menu ends up with a PHP fatal error call to a member schema() on a non-object in ... kernel/setup/systemupgrade.php on line 66. Checking file consistency is OK.

    Returning back to 4.1 is OK. My site is currently under 4.0.

    Thank you in advance for your input on this problem.
  • Corruption of kernel on centos 5.1

    Machine installed with PHP5.2.11. Running through the upgrade procedure from 4.1 to 4.2 for clearing cache, ended up corrupting kernel. Liniux machine seems to be corrupted and cannot boot anymore?

    Any one having the same problem?

    root@INTRANET intradev]# php update/common/scripts/4.2/fixorphanimages.php
    This script will delete images that look orphan
    Press ctrl-c in the next 10 seconds to prevent the script from starting...
    Looking for obsolete image files...
    1164 / 1164 [=======================================================>] 100.00%
    [root@INTRANET intradev]# php bin/php/ezcache.php --clear-all --purge
    Purging : Cache d'affichage de contenu, Cache Global INI, Cache INI, Cache codep age, Cache des identifiants de classes, Cache des clés de classement, Cache des alias d'URL, Cacher de transformation des caractères, Alias d'image, Cache des templates, Cache des template block, Cache des templates override, Cache des te xtes convertis en imagePHP Fatal error: Allowed memory size of 16777216 bytes e xhausted (tried to allocate 262144 bytes) in /var/www/html/intradev/kernel/class es/clusterfilehandlers/ezfsfilehandler.php on line 862

    Fatal error: eZ Publish did not finish its request
    The execution of eZ Publish was abruptly ended, the debug output is present belo w.
    [root@INTRANET intradev]# php bin/php/ezcache.php --clear-all --purge
    bash: /usr/bin/php: Aucun fichier ou répertoire de ce type
    • Re: Corruption of kernel on centos 5.1

      Issue tracker, with patch (not yet approved):

      The bug can occur if the script is run as root and '/' is used as cache path for texttoimage cache. If not run as root, it can still delete files accessible by the user it is running as.
  • Permissions required for EZOE

    If you are doing an upgrade the online editor requires access permissions to work.See
  • Path of updateimagesystem.php

    You should probably give the path of updateimagesystem.php - it's update/common/scripts/4.1/updateimagesystem.php .