Path

ez.no / documentation / ez publish / upgrading / upgrading to 4.1 / 4.0.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.0.x to 4.1.y

This section describes how to upgrade your existing eZ Publish 4.0.x installation to version 4.1.y. If you are upgrading from version 4.0.3 or earlier, you need to first upgrade to 4.0.3 before you can upgrade to 4.1. (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:

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

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

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

Check the eZ Components 2008.2 requirements

With eZ Publish 4.1.0, eZ Components 2008.2 is the minimum version required. If you installed a previous version with PEAR, please upgrade to version 2008.2. For more information see also http://ezcomponents.org/docs/install

Step 1: Upgrading the distribution files

The easiest way to upgrade the distribution files is to unpack eZ Publish 4.1.0 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 (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, you will need to have the following rewrite rule if using Virtual Hosts:

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

For extension development: when using modules always make sure that $Result['path'] is assigned an array even if it's an empty one:

$Result['path'] = array();

For more detailed instructions, see the dedicated doc page: http://ez.no/doc/extensions/online_editor/5_x/installation

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.1.x series of eZ Publish for the first time, and the installation at hand have been running since eZ Publish < 3.3 then you need to run the updateimagesystem.php script before running any of the dbupdate scripts for version 4.1.0 or 4.1.1.

If the installation at hand is a new installation or based on any eZ Publish version >= 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.1/dbupdate-4.0.0-to-4.1.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 has also some changes, for example the autoload array for extensions is now placed in var/autoload of your eZ Publish installation (along teh 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

The update scripts are located in <root of ez publish installation>/update/common/scripts/4.1

  • addlockstategroup.php: is used for creating locked states, part of the object states functionality. It might be useful to know that you can only execute this script once. If you wish to run it a second time, it must be done like this:
    truncate ezcobj_state  ;
    truncate ezcobj_state_group         ;
    truncate ezcobj_state_group_language    ;
    truncate ezcobj_state_language         ;
    truncate ezcobj_state_link             ;
     
    php update/common/scripts/4.1/addlockstategroup.php -sezwebin_site_admin
    
  • fixclassremoteid.php: is used to fix remote ids of classes.
  • fixezurlobjectlinks.php: is used to fix older occurrences of link items not being present in the ezurl_object_table for all versions/translations.
  • fixobjectremoteid.php: is used to fix non-unique usage of content object remote ID's.
  • initurlaliasmlid.php: initialize the ezurlalias_ml_incr table, part of the fixed issue #14077: eZURLAliasML database table lock and unlock code causes implicit commit of database transaction.
  • 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.

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.1 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 subdirectories 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 backup of existing website state including database, extensions, INI settings, etc. During upgrade process existing ezflow and ezwebin extensions will be removed and replaced with 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

eZ Publish 4.1 comes with eZ Flow upgrade script which allows upgrade from previous version to the latest 1.1-0 version. To run upgrade process in automatic mode simply execute following command from eZ Publish root folder.

php bin/php/ezflowupgrade.php --to-version=1.1-0 --url=http://packages.ez.no/ezpublish/4.1/4.1.0

It is very important that user which will execute the upgrade script had correct permissions to modify content user extension, settings and var folders.

In order to get more information about available upgrade options, execute ezflowupgrade.php script with –help param.

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

Upgrading Website Interface is very similar to eZ Flow upgrade process. In order to upgrade existing installation to latest 1.4-0 version simply execute following command from eZ Publish root folder:

php bin/php/ezwebinupgrade.php --to-version=1.4-0 --url=http://packages.ez.no/ezpublish/4.1/4.1.0


Again, it is very important that user which will execute the upgrade script had correct permissions to modify content user extension, settings and var folders.
In order to get more information about available upgrade options, execute ezwebinupgrade.php script with –help param.

php bin/php/ezwebinupgrade.php --help

 

Step 5: 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 (along teh 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

Łukasz Serwatka (26/05/2009 1:00 pm)

Ester Heylen (04/02/2010 2:47 pm)

Łukasz Serwatka, André R., Ester Heylen


Comments

  • PostgreSQL requirement

    Hi

    Maybe it's useful too mention here as well that the minimum version requirement of PostgreSQL has changed?
  • A note about clearing caches

    In current releases (up to 4.1.2 at least) the translation cache is not cleared when the cache-cleanup script is run or the "clear all caches" button is pressed in the admin interface. SO to get the new translations in place, you might need to go and delete the var/siteaccces_name/cache/translation folder by hand
  • Explain "Install eZ Flow and WI separately"

    You should probably explain who must upgrade eZ Flow and the Website Interface separately. I'm still not sure whether or not I should do it.
  • Upgrade 4.0.3 to 4.1.3 eZ Flow problem

    For sites that started at 4.0.3, upgrade is fluid and beautiful, very worthwhile upgrade.

    For sites that started at 4.0.1, then are migrated to 4.0.3 prior to upgrade to 4.1.3, upgrade fails at the eZ Flow, eZ webin stage. "Faild .. err=1"

    I believe I have traced the problem to eZ-Systems-eZ-systems duplication of folder names in /var/storage/packages. I think the installer for eZ Flow must have added the uppercase S folder prior to 4.0.3.

    Surely there is a simple way to cure this problem. I have tried copying contents of uppercased S folder to lowercase s folder, deleting the extra folder and moved the error to a php error message about non-object reference on line 843

    If anyone can relate simple fix, I doubt I am the only one who will bump into this.

    Cheers.
    • Re: Upgrade 4.0.3 to 4.1.3 eZ Flow problem

      Simple fix. Run a re-install of 4.0.3 or higher after standardizing on eZ-systems folder structure.

      settings/override/site.ini.append and set CheckValidity=true

      The installer runs when site is next accessed. Include the eZ Flow extension, do not allow any changes to database. Has worked on a couple of problem sites so far.

      ezwebin_setup-1.3.pdf for more thoughts and more complete instruction.
      • Re: Re: Upgrade 4.0.3 to 4.1.3 eZ Flow problem

        Still simpler solution using admin gui, Setup->Packages
        Notice both an eZ-Systems and eZ-systems repository? That is the problem.

        To fix.
        Deleted the 1.0.2 or older version of ezflow_site from eZ-Systems repository.
        ssh into site and remove the now empty eZ-Systems folder from var/packages
        Reload package manager and note that eZ-Systems repository is gone, eZ-systems remains.
        Download http://packages.ez.no/ezpublish/4.0/4.0.3/ezflow_site.ezpkg to local file system.
        While still in package manager interface click button [Import new package], browse to and select the freshly downloaded package.
        Check repositories again, and note that eZ-Systems was not re-created, rather the ezflow_site package version 1.0.3 resides in the eZ-systems repository.

        Upgrade should now go smoothly.
        One other note -- always check var/log/error.log for other potential problems before upgrades.
  • Autoload generation problem

    It might be worth noting that the autoload generation mechanism now depends on the php Tokenizer extension. On most platforms it shouldn't be a problem, but if (like us, for example) you're running on a Gentoo box and you hand-compiled your php without this extension, well, guess what... do it again!

    Of course, eZ-style, the call to token_get_all() fails silently (thank you mister @), so you could spend some time hacking around in the kernel to find this... ;-)

    HTH.
  • Upgrade infinite loop?

    It reads:
    "If you are upgrading from version 4.0.3 or earlier, you need to first upgrade to 4.0.3 before you can upgrade to 4.1."
    

    So once I upgrade to 4.0.3, I read this again, and it tells me again to upgrade to 4.0.3...

    BTW. While I'm writing this comment, I'm no logger logged in... is it a cache problem or some other problem with the site?
    • Re: Upgrade infinite loop?

      Been a while since I have been through an upgrade, but from memory, I believe that is a simple notification to make you aware.

      If memory serves, there is nothing to prevent proceeding past that notice and completing the upgrade. It is not so much "telling" you as notifying everyone. Please correct me if I am mistaken and I will dig through notes to provide better answer.

      Cheers.
  • Object state script can be executed only once : addlockstategroup.php

    If you run addlockstategroup.php script second time then it will not work.

    If you wish to execute this script again then do the following:
    truncate ezcobj_state  ;
    truncate ezcobj_state_group         ;
    truncate ezcobj_state_group_language    ;
    truncate ezcobj_state_language         ;
    truncate ezcobj_state_link             ;
     
    php update/common/scripts/4.1/addlockstategroup.php -sezwebin_site_admin
    


    I required it today , because I did test upgrade last week and today I was doing final upgrade with latest database and then I just imported latest database to mysql without dropping the database and then many objects were missing the object state then I have to do above steps :-)



  • Update step is repeated

    "Step 3: updateimagesystem.php" is repeated under "Step 6: Running the system upgrade scripts", while it shouldn't. Please correct this.