This section describes how to upgrade your existing eZ Publish 4.2.x installation to version 4.3. 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:

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

1. Upgrade the distribution files to 4.3
2. Upgrade custom extensions
3. Upgrade the database to 4.3
4. Regenerate the autoload array for extensions
5. Run the system upgrade scripts for 4.3
6. (Optional) Enable Admin2 design for the eZ Publish Administration interface
7. Clear the caches

Check for requirements

The eZ Components 2009.1 requirements

With eZ Publish 4.2, eZ Components 2009.2.1 is the minimum version required. When downloading eZ Publish 4.3 it is possible to choose between a package bundled with eZ Components 2009.2.1, or a package without eZ Components. If you choose the latter, you must install eZ Components separately. For more information see http://ezcomponents.org/docs/install

The PHP requirements

eZ Publish 4.3 is now also compatible with PHP version 5.3. For more information regarding system requirements check out http://ez.no/ezpublish/requirements

Step 1: Upgrade the distribution files

The easiest way to upgrade the distribution files is to unpack eZ Publish 4.3 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 site accesses.

Important note

Because the new directory has replaced the original directory, the directory permissions need to be fixed. Use the following commands to do this.

(You have the choice between Shell commands or Alternative shell commands):

•  Shell commands

These shell commands will give proper permission to the web server:

cd </path/to/your/eZ/Publish/directory>
 
chmod -R a+rwx design  extension settings var

•  Alternative shell commands

These commands will setup the permission more correctly, but require knowledge about the running web server.

chmod -R og+rwx design extension settings var
 
chown -R nouser:nouser  design extension settings var

Step 2: 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 are included in eZ Publish, which currently are eZ Online Editor (5.x), eZ OpenOffice.org (2.x) and eZ JSCore (1.x). 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.

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

•  eZ Website Toolbar
•  eZ Star Rating
•  eZ Google Maps Location

For eZ OE 5.x and eZ JS Core you will need to replace the following rewrite rules when using Virtual Hosts:

RewriteRule ^/var/cache/texttoimage/.* - [L]
 
RewriteRule  ^/var/[^/]+/cache/(texttoimage|public)/.* - [L]

with:

RewriteRule ^/var/([^/]+/)?cache/(texttoimage|public)/.* - [L]

For more detailed instructions, see the dedicated eZ OE and eZ JS Core doc pages.

Step 3: Upgrade the database

The update script for the database is located in

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

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

Step 4: 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 the root of your eZ Publish directory:

php bin/php/ezpgenerateautoloads.php --extension

Step 5: Run the system upgrade scripts

Run the following command from the root of your eZ Publish directory:

php update/common/scripts/4.3/updatenodeassignment.php

Step 6: [optional] Enable admin2 design for eZ Publish Administration interface

To enable admin2 open site.ini for your admin site access. For an eZ Flow site this would for instance be:

settings/siteaccess/ezflow_site_admin/site.ini.append.php

In this file include AdditionalSiteDesignList[]=admin2 to your [DesignSettings]. It is important that you add the admin2 design before the admin design, in order to let extensions that have admin templates to continue to work. On an eZ Flow site, it would mean changing the settings from:

[DesignSettings]
SiteDesign=ezflow_site_admin
AdditionalSiteDesignList[]=admin
AdditionalSiteDesignList[]=ezflow

to

[DesignSettings]SiteDesign=ezflow_site_admin
AdditionalSiteDesignList[]=admin2
AdditionalSiteDesignList[]=admin
AdditionalSiteDesignList[]=ezflow

When using a plain or eZ Webin install you should make the same changes. In this case you will of course have a different SiteDesign setting and no AdditionalSiteDesignList[]=ezflow line.

To enable users to change their Administration Interface preferences (for example their preview tab preferences), add the following line to the [Toolbar_admin_right] block in settings/siteaccess/<siteaccess_name>/toolbar.ini.append.php:

Tool[]=admin_preferences

So the block will then look like this:

[Toolbar_admin_right]
Tool[]
Tool[]=admin_current_user
Tool[]=admin_bookmarks
Tool[]=admin_preferences

Last step is to make sure ezjscore (extension) is enabled. For enabling extensions in general, look here, for 4.3 just make sure ezjscore is before ezwebin in ActiveExtensions if you use webin.

Step 7: Clear the caches

Whenever an eZ Publish solution is upgraded, all caches must be cleared in a proper way. Note: You should not be a root user when you start the caching process (refer to http://issues.ez.no/15823). The caching should be done from within a system shell:

1.  Navigate into the eZ Publish 4.3 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.

Upgrade eZ Flow and/or Website Interface separately

Please visit the eZ Flow and eZ Webin upgrade documentation for more info.