This section describes how to upgrade your existing eZ Publish 3.9.x installation to version 3.9.y, for example from 3.9.0 to 3.9.5. If you are upgrading from a version prior to eZ Publish 3.9.0, you should first upgrade to 3.9.0 as described in this section.

Important note

Before continuing, note that it is strongly recommended to upgrade directly to the latest stable release in the 3.9 branch (3.9.5 at the time of writing), which contains all important bug fixes. Refer to the changelogs and security advisories for more information about the issues that were fixed in the latest releases or view the short list of changes below.

• There is a significant problem with eZ Publish 3.9.0 - 3.9.2. More precisely, the discount functionality of the shop module contains a security vulnerability. The same bug exists in eZ Publish 3.8.0 - 3.8.8. This issue was fixed in eZ Publish 3.8.9, 3.9.3 and 3.10.0. Refer to the announcement for details.
• eZ Publish versions 3.9.0 - 3.9.3 contain a security vulnerability that can be used to show hidden content on a public siteaccess. The same bug exists in eZ Publish 3.8.0 - 3.8.9. This issue was fixed in eZ Publish 3.8.10, 3.9.4 and 3.10.0. Refer to the announcement for details.
• The "updatetipafriendpolicy.php" upgrade script in eZ Publish 3.9.3 - 3.9.4 contains a bug. The same bug exists in eZ Publish 3.10.0. It prevents the script from granting access to the "Tip a friend" feature to users. The problem occurs when the script is run on Windows. This issue was fixed in eZ Publish 3.9.5, 3.10.1 and 4.0.0. Refer to http://issues.ez.no/11663 for more information.
• The "updatevatcountries.php" upgrade script in eZ Publish 3.9.3 - 3.9.4 contains a bug. The same bug exists in eZ Publish 3.10.0. This issue was fixed in eZ Publish 3.9.5, 3.10.1 and 4.0.0. Refer to http://issues.ez.no/11955 for more information.
• In eZ Publish 3.9.0 - 3.9.4, there is a bug in the "File" datatype which may cause problems with binary file uploading via WebDAV. The same bug exists in eZ Publish 3.10.0. This issue was fixed in eZ Publish 3.9.5, 3.10.1 and 4.0.0. Refer to http://issues.ez.no/9450 for more information.
• In eZ Publish 3.9.4, some cache related settings in the "settings/site.ini" configuration file were changed by mistake. This issue was fixed in eZ Publish 3.9.5. Refer to http://issues.ez.no/11647 for more information.
• In eZ Publish 3.9.4, the "register" view of the "user" module contains a bug. It prevents the system from registering new users when the "VerifyUserEmail" setting is enabled (it is enabled by default). The same bug exists in eZ Publish 3.8.10 and 3.10.0. This issue was fixed in eZ Publish 3.9.5 and 3.10.1. Refer to http://issues.ez.no/11598 for more information.

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.9.5
2. Upgrading the database to 3.9.5
3. Running the system 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.9.5 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).

If you are using the Website Interface front-end, make sure you copied the "extension/ezwebin/" directory. It is also possible to upgrade the Website Interface extension to a newer version (you can find more information and instructions in the "Upgrading the Website Interface" chapter of the Website Interface installation guide).

Important bug fix for remote IDs

Due to some bugs in previous versions of eZ Publish (3.9.0 and others), it might happen that not all content objects in your database have unique remote IDs. This basically means that the "remote_id" column of the "ezcontentobject" table in the database might contain duplicate values. In eZ Publish 3.9.5, a database schema change was introduced in order to ensure that only unique remote IDs can be stored in this table. Because of this, you need to make sure that there are no content objects with identical remote IDs before upgrading the database. This can be done by running the "fixobjectremoteid.php" upgrade script. (Note that both the database schema change and the upgrade script were added to eZ Publish 3.10.1 and 4.0.1 as well.)

This script should be run once for each database, specifying one siteaccess per database. If you only have a public and an administration siteaccess that share the same database (which is the most typical/usual case), you only need to run the script for one of the siteaccesses. If the siteaccess isn't specified, the default siteaccess will be used.

The following example shows how to run the script:

1. Navigate into the eZ Publish 3.9.5 directory.

2. Run the script (replace "example" with the actual name of your siteaccess):

   php update/common/scripts/3.9/fixobjectremoteid.php -s example
   

The script will search for objects with non-unique remote IDs. Every time such an object is found, the script will suggest to either display more detailed information or fix the problem automatically. If you choose the first option, the script will display the list of objects that have the same remote ID and let you decide which one should remain unchanged; all other objects in the list will get new remote IDs. Otherwise, the script will fix the problem automatically based on the objects' creation dates. This means that the script will generate new remote IDs for all objects in the list except the one that was created first.

The optional "--mode" parameter makes it possible to run the script in either "auto-fix" or "manual-fix" mode as shown below.

php update/common/scripts/3.9/fixobjectremoteid.php -s example --mode=value

If you replace "value" with "a" in the command above, the script will automatically fix all non-unique remote IDs that are found in the database based on the objects' creation dates. In this case, no further input is required from the user. If you specify "--mode=d", the script will display the list of objects for each non-unique remote ID so that you can manually choose which objects should keep their remote IDs.

Step 2: Upgrading the database

To upgrade a 3.9.0 database to 3.9.5, you should navigate into the eZ Publish 3.9.5 directory and run the following database upgrade scripts one after another:

1. dbupdate-3.9.0-to-3.9.1.sql
2. dbupdate-3.9.1-to-3.9.2.sql
3. dbupdate-3.9.2-to-3.9.3.sql
4. dbupdate-3.9.3-to-3.9.4.sql
5. dbupdate-3.9.4-to-3.9.5.sql

MySQL

The database upgrade scripts are located in the "update/database/mysql/3.9/" directory of your eZ Publish installation. Each of these scripts can be launched using the following shell command:

mysql -u <username> -p<password> <database> < update/database/mysql/3.9/dbupdate-3.9.x-to-3.9.y.sql

PostgreSQL

The database upgrade scripts are located in the "update/database/postgresql/3.9/" directory of your eZ Publish installation. Each of these scripts can be launched using the following shell command:

psql -d <database> -U <dbowner> < update/database/postgresql/3.9/dbupdate-3.9.x-to-3.9.y.sql

Step 3: Running the system upgrade scripts

The 3.9.1 - 3.9.5 versions of eZ Publish introduce a couple of important bug fixes and functionality changes. In order to make sure that your site is compatible with these changes, you may need to run a few upgrade scripts.

Changes to roles and policies

From 3.9.3, users (typically those to which the anonymous role applies) need to have access to the "tipafriend" function of the "content" module in order to use the "Tip a friend" feature. Because of compatibility reasons, you need to run the "updatetipafriendpolicy.php" script.

Note for Linux/UNIX users: there is no need to run the script if you previously upgraded to 3.8.9 or a later version in the 3.8.x branch.

Note for Windows users: in eZ Publish 3.9.3 - 3.9.4 the "updatetipafriendpolicy.php" script contains a bug that prevents it from granting access to the "Tip a friend" feature to the users. The same bug exists in eZ Publish 3.8.9 - 3.8.10 and 3.10.0 (refer to http://issues.ez.no/11663 for more information). The updated version of the script is available in eZ Publish 3.9.5, 3.10.1 and 4.0.0. Windows users that previously upgraded to 3.8.9 - 3.8.10 or 3.9.3 - 3.9.4 using the original version of the script are encouraged to re-run this script when upgrading to 3.9.5.

The following example shows how to run the script:

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

   php update/common/scripts/3.9/updatetipafriendpolicy.php -s example_admin -l login -p password
   

   Replace "example_admin" with the actual name of your admin siteaccess, use the administrator's login and password instead of "login" and "password".

The script will add a new role that grants access to the "Tip a friend" feature and ask for confirmation about assigning this role to each user or user group located one level beneath the "Users" top level node.

Improved handling of country dependent VATs

In eZ Publish version 3.9.3 - 3.9.5, the handling of country dependent VATs has been improved. In order to make sure that your site is compatible with the changes, you need to run the "updatevatcountries.php" script.

Note that the "updatevatcountries.php" upgrade script in eZ Publish 3.9.3 - 3.9.4 contains a bug. The same bug exists in eZ Publish 3.10.0 (refer to http://issues.ez.no/11955 for more information). The updated version of the script is available in eZ Publish 3.9.5, 3.10.1 and 4.0.0. If you previously upgraded to 3.9.3 or 3.9.4 using the original version of the script, you need to run the updated version of the script when upgrading to 3.9.5.

The "updatevatcountries.php" script should be run once for each database, specifying one siteaccess per database. If you only have a public and an administration siteaccess that share the same database, you only need to run the script for one of the siteaccesses. If the siteaccess isn't specified, the default siteaccess will be used.

The following example shows how to run the script:

1. Navigate into the eZ Publish 3.9.5 directory.
2. Run the "updatevatcountries.php" script (replace "example" with the actual name of your siteaccess):

   php update/common/scripts/3.9/updatevatcountries.php -s example
   

The script will go through all the VAT rules in the database and make them compatible with the newly introduced changes.

Binary files uploaded via WebDAV (optional)

In eZ Publish 3.9.0 - 3.9.4, there is a bug in the "File" datatype which may cause problems with binary file uploading via WebDAV. The typical symptoms are that the file extension of the uploaded file is missing and that you may not be able to download the file once it is uploaded (refer to http://issues.ez.no/9450 for more information). The same bug exists in eZ Publish 3.8.6 - 3.8.10 and 3.10.0. This issue was fixed in eZ Publish 3.9.5, 3.10.1 and 4.0.0.

If your site has objects that were created by uploading files via WebDAV and you have configured MIME-type-to-class mapping using the "MimeClassMap[]" directive in an override for "upload.ini", you need to run the "updatebinaryfile.php" script in order to fix the file extensions. (If a content class does not have any attributes that make use of the "File" datatype, instances of this class are not affected.)

The "updatebinaryfile.php" script should be run once for each database, specifying one siteaccess per database. If you only have a public and an administration siteaccess that share the same database, you only need to run the script for one of the siteaccesses. If the siteaccess isn't specified, the default siteaccess will be used.

The following example shows how to run the script:

1. Navigate into the eZ Publish 3.9.5 directory.
2. 1.Run the script (replace "example" with the actual name of your siteaccess):

   php update/common/scripts/3.9/updatebinaryfile.php -s example
   

The script will go through all the binary files and fix their extensions. The filename entries stored in the "ezbinaryfile" database table will be changed accordingly.

Step 4: Updating the system configuration

You are not required to do any configuration changes when upgrading from 3.9.0 to 3.9.5.

Default configuration of caches (optional)

In eZ Publish versions prior to 3.9.4, the default configuration enables view caching, template caching and template compiling. (This configuration of caches is recommended for live sites. During development, these features can be turned off by disabling the "ViewCaching", "TemplateCache" and "TemplateCompile" directives within an override for "site.ini".) However, this default configuration was accidentally changed in eZ Publish 3.9.4 (refer to http://issues.ez.no/11647 for more information). The change is reverted in eZ Publish 3.9.5.

Default configuration of unique user emails (optional)

In eZ Publish versions prior to 3.8.0, the default configuration does not allow different users to be registered with the exact same email address. This is just a built-in precaution mechanism which can be easily turned off by setting the "RequireUniqueEmail" directive within the [UserSettings] block of a configuration override for "site.ini" to "false". However, this default configuration was accidentally changed in eZ Publish version 3.8.0 (refer to http://issues.ez.no/9643 for more information). The change is reverted in eZ Publish versions 3.8.7 and 3.9.1.

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

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

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 "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are any cache files left, you need to remove them manually.