This section describes how to upgrade your existing eZ publish 3.3-5 installation to version 3.4.0. If you are upgrading from a version prior to eZ publish 3.3-5, you need to first upgrade to 3.3-5 before you can upgrade to 3.4.0.

Please make sure that you have a working backup of the site before you do the actual upgrade. The upgrade procedure consists of the following steps:

1. Upgrading the distribution files to 3.4.0
2. Upgrading the database to 3.4.0
3. Running the 3.4.0 upgrade scripts
4. Updating the system configuration
5. Clearing the caches

Step 1: Upgrading the distribution files

The easiest way to upgrade the distribution files is to unpack eZ publish 3.4.0 to a 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 actual names used by your siteaccesses.

Custom extensions

If you are using custom extensions then 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 (for example the "PayPal" extension).

Step 2: Upgrading the database

The following text describes how a 3.3-5 database can be upgraded to 3.4.0.

MySQL

1. Navigate into the eZ publish 3.4.0 directory.
2. Run the database upgrade script:

   mysql -u<username> -p<password> <database> < update/database/mysql/3.4/dbupdate-3.3-5-to-3.4.0.sql
   

PostgreSQL

1. Navigate into the eZ publish 3.4.0 directory.
2. Run the database upgrade script:

   psql -d <database> -U <dbowner> < update/database/postgresql/3.4/dbupdate-3.3-5-to-3.4.0.sql
   

Step 3: Running the 3.4.0 upgrade scripts

The 3.4.0 version of eZ publish introduces a couple of new features. In order to make sure that your site is compatible with these features, you'll have to run a couple of upgrade scripts.

Remote ID

In eZ publish 3.4.0, a new attribute called "remote_id" has been added to content objects, classes and nodes. This attribute stores a global unique ID for an object/class/node. The remote ID is an MD5 hash of the time when the object/class/node was created plus a random value. These IDs are used in order to avoid collisions of identical objects/classes/nodes when importing and exporting data from one site to another. You need to run the "updateremoteid.php" script in order to make sure that all your items that support the remote ID gets one generated:

1. Navigate into the eZ publish 3.4.0 directory.
2. Run the script (replace "example" with the name of your siteaccess(es)):

   php update/common/scripts/updateremoteid.php
   

Updating the session data

In eZ publish 3.4.0, the session functionality has been improved in order to relate a session to a user (see the 3.4.0 changelog for more information). The session data in the "ezsession" table now contain information about the session user. This allows to easily count the number of active registered users and anonymous users. When a user is being removed or disabled, the system will remove the corresponding session(s) in order to automatically log out invalid users. In order to update the entries in the "ezsession" table, you need to run the "updatesession.php" script:

1. Navigate into the eZ publish 3.4.0 directory.
2. Run the script:

   php update/common/scripts/updatesession.php
   

Top level nodes/objects changes

In eZ publish 3.4.0, a new top level node/object called "Setup" has been added. You need to run the "updatetoplevel.php" script for your admin siteaccess in order to make sure that all your top level nodes are properly configured (replace "example_admin" with the actual name of your admin siteaccess):

1. Navigate into the eZ publish 3.4.0 directory.
2. Run the script:

   php update/common/scripts/updatetoplevel.php
   

The script will check the top level nodes and match them with the values defined under the "[NodeSettings]" section of the "content.ini" configuration file or its override. If "content.ini" or its override contains incorrect IDs of the top level nodes, these will be automatically updated. If some of the top level nodes are missing, these will be created.

Changes in the shop order system

In eZ publish 3.4.0, the webshop functionality has been improved (see the 3.4.0 changelog for more information). The list of orders that is stored in the "ezorder" database table now includes the customer's email for each order. If you are using the eZ publish webshop functionality on your site and your order list is not empty, then you need to run the "addorderemail.php" script when upgrading to 3.4.0:

1. Navigate into the eZ publish 3.4.0 directory.
2. Run the script:

   php update/common/scripts/addorderemail.php
   

The script will modify the "ezorder" table in the database.

Step 4: Updating the system configuration

You are not required to do any configuration changes when upgrading from 3.3-5 to 3.4.0. However, please note that it is not recommended to use "admin" as a name of your administration siteaccess. This name is reserved by the system and your changes to the "admin" siteaccess will be lost during the upgrade process because of overwriting the files in the "settings/siteaccess/admin" directory. Trying to use the "admin" siteaccess may cause problems when upgrading. A typical symptom is that everything is working fine after upgrading, except for some parts of your administration interface, e.g. media and user tabs do not work. To solve this, create a new siteaccess called for example "my_admin" and copy the altered files from your backup to "settings/siteaccess/my_admin".

Step 5: 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 3.4.0 directory.
2. Run the clear cache script:

   bin/shell/clearcache.sh --clear-all
   

Please make sure that all caches are cleared. Sometimes the script is unable to clear caches because of restrictive file/directory permission settings. Make sure that all caches have been cleared by inspecting the contents of the various cache subdirectories within the "var" directory.