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

Important note

Before continuing, note that version 3.8 is no longer supported. Instead of running eZ Publish 3.8, you should consider upgrading to one of the supported versions. If you want to run 3.8 anyway, make sure you upgrade to version 3.8.10, which is the latest stable release in the 3.8 branch. Refer to the changelogs for more information about the issues that were fixed in the latest 3.8.x releases or view the short list of changes below.

• There is a significant problem with eZ Publish 3.8.0 - 3.8.8. More precisely, the discount functionality of the shop module contains a security vulnerability. The same bug exists in eZ Publish 3.9.0 - 3.9.2. The 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.8.0 - 3.8.9 contain a security vulnerability that can be used to show hidden content on a public siteaccess. The same bug exists in eZ Publish 3.9.0 - 3.9.3. This issue was fixed in eZ Publish 3.8.10, 3.9.4 and 3.10.0. Refer to the announcement for details.

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.8.10
2. Upgrading the database to 3.8.10
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.8.10 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.

Important bug fix for the "user" module

In eZ Publish 3.8.10, 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.9.4 and 3.10.0 (refer to http://issues.ez.no/11598 for more information). This issue will be fixed in the upcoming eZ Publish 3.9.5 and 3.10.1 releases. In order to make your user registration mechanism work properly in 3.8.10, you have to download the updated version of "kernel/user/register.php" from http://pubsvn.ez.no and replace the corresponding file in your installation.

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

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

1. dbupdate-3.8.0-to-3.8.1.sql
2. dbupdate-3.8.1-to-3.8.2.sql
3. dbupdate-3.8.2-to-3.8.3.sql
4. dbupdate-3.8.3-to-3.8.4.sql
5. dbupdate-3.8.4-to-3.8.5.sql
6. dbupdate-3.8.5-to-3.8.6.sql
7. dbupdate-3.8.6-to-3.8.7.sql
8. dbupdate-3.8.7-to-3.8.8.sql
9. dbupdate-3.8.8-to-3.8.9.sql
10. dbupdate-3.8.9-to-3.8.10.sql

Note that there are seven version-focused upgrade scripts, meaning that seven of the scripts in the list contain only two lines (that simply update the version number) and can be skipped. Therefore, the list of scripts to run contains three items instead of ten:

1. dbupdate-3.8.0-to-3.8.1.sql
2. dbupdate-3.8.4-to-3.8.5.sql
3. dbupdate-3.8.9-to-3.8.10.sql

Running these three scripts is equivalent to running all the ten scripts mentioned above.

MySQL

The database upgrade scripts are located in the "update/database/mysql/3.8/" 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.8/dbupdate-3.8.x-to-3.8.y.sql

PostgreSQL

The database upgrade scripts are located in the "update/database/postgresql/3.8/" 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.8/dbupdate-3.8.x-to-3.8.y.sql

Step 3: Running the system upgrade scripts

Custom classes in XML tags

In eZ Publish 3.8.0 and earlier versions, you could use custom classes in XML tags without having to specify them first. From eZ Publish 3.8.1, you have to specify the names of all custom classes that are used within XML tags. The names of the classes must be added to the global (or siteaccess) "content.ini.append.php" configuration file. For example, you will not be able to use "pRed" and "pBlue" classified paragraphs in your XML blocks unless you have the [paragraph] section in "content.ini.append.php" containing the following lines:

AvailableClasses[]
AvailableClasses[]=pRed
AvailableClasses[]=pBlue

If you are using XML tag classes that are not listed in "content.ini" on your site, you will need to add the necessary configuration settings manually or run the "correctxmltextclasses.php" script. (If your installation does not include the "correctxmltextclasses.php" script, you need to download it here.)

If all your siteaccesses are using the same database, run the script with the "--global" option as described below.

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

   php update/common/scripts/correctxmltextclasses.php --global
   

The script will go through the XML blocks stored in the database, check which classes are in use and add missing settings (if any) to the "settings/override/content.ini.append.php" configuration file. If you do not wish to update this configuration file automatically, run the script like this:

php update/common/scripts/correctxmltextclasses.php --dump-only

The script will output the list of classes that need to be specified, for example:

Element 'paragraph': class 'pBlue' is not defined.
Element 'paragraph': class 'pRed' is not defined.

In case if your siteaccesses are using different databases, the classes that are used within XML tags must be specified per siteaccess. This means that the upgrade script must be run for each of your siteaccesses.

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

   php update/common/scripts/correctxmltextclasses.php -s example
   

The script will automatically update the "settings/siteaccess/example/content.ini.append.php" configuration file.

If the siteaccess is not specified then the default siteaccess will be used.

Changes to roles and policies

From 3.8.9, users (typically the anonymous role) 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 Windows users: in eZ Publish 3.8 the "updatetipafriendpolicy.php" script contains a bug that prevents it from granting access to the "Tip a friend" feature to the users. Refer to http://issues.ez.no/11663 for more information about the problem and the solution.

The following example shows how to run the script:

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

   php update/common/scripts/3.8/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.

Step 4: Updating the system configuration

Updating INI settings for "html" classification

In eZ Publish versions from 3.8.0 to 3.8.3 it is possible to include HTML code in XML blocks by using the "html" classification. However, this feature can also be used to insert JavaScript code, making it possible for users with sufficient privileges to make an XSS exploit. This feature is therefore disabled by default in eZ Publish 3.8.4 and later, and should only be enabled if you really trust your editors.

To enable html classification, add the following lines to your "content.ini.append.php" file:

[literal]
 # The class 'html' is disabled by default because it gives editors the
 # possibility to insert html and javascript code in XML blocks.
 # Don't enable the 'html' class unless you really trust all users who has
 # privileges to edit objects containing XML blocks.
 AvailableClasses[]=html

Enabling the Online Editor extension (optional)

eZ Publish 3.8.1 and later versions include the Online Editor extension licensed under the GPL. If you wish to use this extension, make sure it is enabled (refer to this section for more information).

Default configuration of unique user emails

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 has been 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 version 3.8.7. If you are going to use eZ Publish 3.8.0-3.8.6, it is recommended to add the following line to the [UserSettings] block of the "override/site.ini.append.php" configuration file:

RequireUniqueEmail=true

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

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

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.