This section describes how to upgrade your existing eZ Publish 3.10.x installation to version 3.10.y, for example from 3.10.0 to 3.10.1. If you are upgrading from a version prior to eZ Publish 3.10.0, refer to the "Upgrading from 3.9.x to 3.10.y" section for upgrade instructions.

It is recommended to upgrade directly to the latest stable release in the 3.10 branch, 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 here.

The upgrade procedure described below is generic and does not cover any specific cases. If you are running eZ Publish in a clustered environment, refer to the developer documentation for upgrade instructions. In case the eZ Publish Extension for Oracle® Database is used, refer to the documentation of the database extension.

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.10.1
2. Upgrading the database to 3.10.1
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.10.1 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 the actual names of your siteaccesses.

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 "ezdhtml", "ezodf", "ezpaypal" and "ezurlaliasmigration").

If you are using the Website Interface front-end, be sure to copy 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.10.1, 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.9.5 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.10.1 directory.

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

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

The following text describes how a 3.10.0 database can be upgraded to 3.10.1.

MySQL

1. Navigate into the eZ Publish 3.10.1 directory.
2. Run the database upgrade script:

   mysql -u <username> -p<password> <database> < update/database/mysql/3.10/dbupdate-3.10.0-to-3.10.1.sql
   

Note that the CREATE TABLE statement in the database upgrade script does not specify which storage engine to use (no ENGINE or TYPE option), and thus the default storage engine will be used. Normally, it is MyISAM (starting from MySQL v.3.23). If you are using InnoDB, make sure the default storage engine is set to InnoDB before you run the database upgrade script (refer to the MySQL documentation for information about how to set the default engine). If you were not able to change the MySQL configuration on your server, and the upgrade left you with a mix of table types, you can convert the newly created table to InnoDB using the following SQL query:

ALTER TABLE ezurlwildcard TYPE = innodb;

It is also possible to use the "bin/php/ezconvertmysqltabletype.php" script for database conversion.

PostgreSQL

1. Navigate into the eZ Publish 3.10.1 directory.
2. Run the database upgrade script:

   psql -d <database> -U <dbowner> < update/database/postgresql/3.10/dbupdate-3.10.0-to-3.10.1.sql
   

Step 3: Running the system upgrade scripts

The 3.10.1 version of eZ Publish introduces 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.

Multi-language support for URL aliases

In eZ Publish 3.10.1, the multi-language support for URL aliases was substantially improved, along with some important bug fixes related to this functionality. In addition, the "bin/php/updateniceurls.php" script was updated and the support for new parameters was added. When upgrading, you need to regenerate all URL aliases that are stored in the "ezurlalias_ml" database table. This basically means that all auto-generated URL aliases will be deleted and then created from scratch by using the "updateniceurls.php" script. However, manual/user-defined URL aliases and URL history entries cannot be regenerated automatically. Instead, these items will be transfered/migrated into a temporary table in the database (hereinafter called "migration table") and then restored at a later stage. This must be done by using the "migrate.php" script, which is included in the "ezurlaliasmigration" extension. This new extension is included in eZ Publish 3.10.1 and provides tools for the purpose of URL alias migration. (Note that the "ezurlaliasmigration" extension was added to eZ Publish 4.0.1 as well.)

Follow the instructions below in order to update your URL aliases.

1. Create a database backup.

Before you continue, create a backup of your database (or at least make sure that you have a backup of the "ezurlalias_ml" table itself).

2. Review your configuration settings.

In eZ Publish 3.10.1 the default type of URL transformation was changed from "urlalias_iri" to "urlalias". Because of this, you must review your URL alias configuration settings as described below.

• If the "TransformationGroup" directive is present in either global override for "site.ini" or "settings/siteaccess/<your_siteaccess>/site.ini.append.php" for all siteaccesses, no configuration changes are required.
• Otherwise, your site makes use of the default type of URL transformation. In eZ Publish 3.10.0, it was "urlalias_iri". When upgrading to 3.10.1, you must explicitly specify "urlalias_iri" using the "TransformationGroup" directive located in the [URLTranslator] section of either "settings/siteaccess/<your_siteaccess>/site.ini.append.php" (for each siteaccess) or "settings/override/site.ini.append.php" (if all your siteaccesses are using the same database).

In other words, make sure that your existing URL alias configuration does not change because of the new default value of the "TransformationGroup" directive introduced in 3.10.1. Without this, there might be some broken or inconsistent URLs on your site after upgrading to 3.10.1.

3. Enable the "ezurlaliasmigration" extension.

The "ezurlaliasmigration" extension must be enabled for all of your siteaccesses. To do this, edit the "site.ini.append.php" file located in the "settings/override" directory and add the following line under the [ExtensionSettings] section:

ActiveExtensions[]=ezurlaliasmigration

Alternatively, you can enable the extension separately for each siteaccess. To do this, edit the "site.ini.append.php" file located in the "settings/siteaccess/example" directory (replace "example" with the name of the target siteaccess) and add the following line under the [ExtensionSettings] section:

ActiveAccessExtensions[]=ezurlaliasmigration

4. Proceed with updating your URL aliases.

In order to update your URL aliases, you need to do the following:

• Create the migration table.
• Transfer your URL aliases to the migration table.
• Remove old URL alias data.
• Create new auto-generated URL aliases.
• Restore migrated URL data.

When upgrading from 3.10.0 to 3.10.1, these operations are exactly the same as when upgrading from version 4.0.0 to 4.0.1. Read the corresponding subsections of the "Upgrading from 4.0.x to 4.0.y" documentation page starting from "4. Create the migration table".

Binary files uploaded via WebDAV (optional)

In eZ Publish 3.10.0, 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.9.4 and earlier versions. 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.)

Refer to the corresponding part of the "Upgrading from 3.9.x to 3.10.y" documentation page for instructions about how to run the "updatebinaryfile.php" script.

Changes to system upgrade scripts (optional)

If your solution was initially built on eZ Publish 3.9 or an earlier version and then upgraded to 3.10.0, read this part carefully. Otherwise, skip this part.

The "updatevatcountries.php" upgrade script in eZ Publish 3.10.0 contains a bug. The same bug exists in eZ Publish 3.9.4 and 3.9.3 (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.10.0 using the original version of the script, you need to run the updated version of the script when upgrading from 3.10.0 to 3.10.1. Refer to the corresponding part of the "Upgrading from 3.9.x to 3.10.y" documentation page for instructions about how to run the "updatevatcountries.php" script.

If you are running eZ Publish on Windows, note that in eZ Publish 3.10.0 there is a bug in the "updatetipafriendpolicy.php" upgrade script that prevents it from granting access to the "Tip a friend" feature to the users. The same bug exists in eZ Publish 3.9.3 - 3.9.4 and 3.8.9 - 3.8.10 (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.10.0 using the original version of the script are encouraged to re-run this script when upgrading from 3.10.0 to 3.10.1. Refer to the corresponding part of the "Upgrading from 3.9.x to 3.10.y" documentation page for instructions about how to run the "updatetipafriendpolicy.php" script.

Step 4: Updating the system configuration

You are not required to do any configuration changes when upgrading from 3.10.0 to 3.10.1.

Tree menu configuration (optional)

eZ Publish 3.10.1 introduces some changes to the dynamic tree menu functionality. In particular, the "treemenu" view of the "content" module no longer makes use of parameters that are transferred using GET variables (this improves tree menu compatibility when running PHP in FastCGI mode; refer to http://issues.ez.no/11806 for more information).

If you have instructed Apache to use "index_treemenu.php" instead of "index.php" when the treemenu view of the content module is requested, this feature will stop working after upgrading to version 3.10.1. To make it work, update your rewrite rules as described below.

If your ".htaccess" file contains the following line:

RewriteRule content/treemenu/?$ index_treemenu.php

you need to remove "$" from there. The updated line should look like this:

RewriteRule content/treemenu/? index_treemenu.php

If no ".htaccess" file is used, check whether the following line is present in your Apache configuration file:

RewriteRule content/treemenu/?$ /index_treemenu.php [L]

If found, remove "$" from this line. The result will look like this:

RewriteRule content/treemenu/? /index_treemenu.php [L]

Note that due to a bug in eZ Publish 3.10.1, you need to download the updated version of "index_treemenu.php" from http://pubsvn.ez.no and replace the corresponding file in your installation. The same bug exists in eZ Publish 4.0.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.10.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 "var/cache/" and "var/<name_of_siteaccess>/cache/" directories). If there are any cache files left, you need to remove them manually.