This documentation page is deprecated and no longer maintained. Refer to the following documentation pages for upgrade instructions:

• Upgrading from 3.10.x to 4.0.y
• Upgrading from 4.0.x to 4.0.y

This section describes how to upgrade your existing eZ Publish 3.10.0 installation to version 4.0.0. If you are upgrading from a version prior to eZ Publish 3.10.0, you need to first upgrade to 3.10.0 before you can upgrade to 4.0.0. In this case, there are two system upgrade scripts that you should skip running when upgrading from 3.9.x to 3.10.0:

• In eZ Publish 4.0, the "bin/php/updateniceurls.php" script was sufficiently improved. In addition, the support for wildcard based URL forwarding was re-added and the default type of URL transformation was changed to "urlalias". Refer to http://issues.ez.no/11650 and http://issues.ez.no/12093 for more information.
• The "updatetipafriendpolicy.php" upgrade script in eZ Publish 3.10.0 contains a bug. 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 4.0.0 (plus the upcoming versions 3.10.1 and 3.9.5). Refer to http://issues.ez.no/11663 for more information.

How to upgrade

Note that in some cases, it is not possible or not recommended to upgrade from version 3.10.0 to 4.0.0. Read the "Important notes" section in order to find out whether you can upgrade immediately or have to delay upgrading until new software releases are available.

The upgrade procedure described below is generic and does not cover any specific cases (for example, running eZ Publish in a clustered environment).

eZ Publish 4.0 contains all the functionality of the 3.10 series. Before upgrading, check the requirements and set up the hosting environment for your site accordingly, so that you can quickly switch to PHP 5 after upgrading the distribution files.

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 4.0
2. Upgrading the database to 4.0
3. Running the 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 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, 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 "ezodf" and "ezdhtml").

If you are using the Website Interface front-end, you will need to upgrade the extension to version 1.3 as earlier versions are not compatible with eZ Publish 4. Refer to the "Upgrading the Website Interface" chapter of the Website Interface installation guide for more information and instructions.

Switching to PHP 5

After upgrading the distribution files, switch your site to use PHP 5 (make sure all the requirements are met).

Note that you need to set the "date.timezone" value in the "php.ini" configuration file. If this setting is not specified, you will most likely receive error messages like "It is not safe to rely on the system's timezone settings" when running eZ Publish on PHP 5. The following example shows how the corresponding line in "php.ini" looks like:

date.timezone = <timezone>

Refer to the PHP documentation for the list of supported timezones. Don't forget to restart Apache after editing "php.ini".

Step 2: Upgrading the database

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

MySQL

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

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

Note that the CREATE TABLE statements in the database upgrade script do 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. 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 4.0.0 directory.
2. Run the database upgrade script:
   

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

Step 3: Running the system upgrade scripts

Binary files uploaded via WebDAV (optional)

In eZ Publish version 3.9.0 - 3.9.4 and 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). This issue was fixed in eZ Publish 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.) This script should be run for all siteaccesses that use different databases. If you only have a public and an administration siteaccess (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 4.0 directory.
2. Run the script (replace "example" with the actual name of your siteaccess):
   

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

Multi-language support for URL aliases (optional)

eZ Publish 4.0 supports wildcard based URL forwarding. This feature was removed when implementing the multilingual URLs functionality for eZ Publish 3.10.0 and then re-added in later versions. In eZ Publish 4.0, the upgrade script for generating multilingual URL aliases was sufficiently improved. In addition, the default type of URL transformation was changed to "urlalias" (refer to http://issues.ez.no/12093 for more information).

If you are upgrading from 3.9.x to 4.0.0, you need to upgrade to 3.10.0 first and then upgrade to 4.0.0. In this case, it is recommended to skip running the "updateniceurls.php" script when upgrading to 3.10.0, and run the updated version of the script when upgrading from 3.10.0 to 4.0.0.

If you are running eZ Publish 3.10.0 and experiencing any problems with multilingual URL aliases, these can be a result of changes that were made by the "updateniceurls.php" script when upgrading to 3.10.0. In order to avoid such problems in the future, it is recommended to revert the changes and run the updated version of the script when upgrading from 3.10.0 to 4.0.0. However, this operation is not safe: in case you have added new custom URL aliases in 3.10.0, these will be lost.

Reverting the changes

In order to revert the changes that were made by the "updateniceurls.php" script when upgrading to 3.10.0, run the following SQL queries:

UPDATE ezurlalias SET is_imported=0;
TRUNCATE ezurlalias_ml;

Running the upgrade script

After reverting the changes, you need to run the upgrade script once again. This procedure is described in the "Multi-language support for URL aliases" section of the 3.10.0 upgrade documentation. However, there are two differences for eZ Publish 4.0:

1. The default value of "TransformationGroup" setting was changed in eZ Publish 4.0 from "urlalias_iri" to "urlalias".
2. In eZ Publish 4.0, the script supports some new parameters, and thus you need to use the following shell command to run the script:
   

   php bin/php/updateniceurls.php --import --fetch-limit=number -s example
   

   Replace "example" with the actual name of the siteaccess and specify the desired number of items to handle per one iteration instead of "number"; the script will automatically do as many iterations as necessary to convert all the URLs, based on the number specified.

The "--import" parameter makes the script go through all entries in the "ezurlalias" database table, which was used for storing URL aliases in eZ Publish 3.9 and earlier versions. As a result, old URL aliases will be imported to the new system and stored in the "ezurlalias_ml" table. This database table is used for storing multilingual URL aliases in eZ Publish 3.10.0 and later versions.

If the optional "--fetch-limit" parameter is omitted, the script will handle 200 items per one iteration.

Changes to roles and policies (optional)

If you are running eZ Publish on Windows, note that in eZ Publish 3.10.0 there is a bug in the "updatetipafriendpolicy.php" 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.4 and earlier versions (refer to http://issues.ez.no/11663 for more information). The updated version of the "updatetipafriendpolicy.php" script is available in eZ Publish 4.0.0 (plus the upcoming versions 3.10.1 and 3.9.5). Windows users are encouraged to re-run this script when upgrading from 3.10.0 to 4.0. The following example shows how this can be done:

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

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

Replace "example_admin" with the actual name of your admin siteaccess and 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 (optional)

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 for download and will be included in the upcoming eZ Publish 4.0.1, 3.10.1 and 3.9.5 releases. If you upgraded to 3.10.0 using the original version of the script, you need to download the updated version from http://pubsvn.ez.no and run it when upgrading from 3.10.0 to 4.0.0.

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 4.0.0 directory.
2. Run the "updatevatcountries.php" script (replace "example" with the actual name of your siteaccess):
   

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

The script will go through all the VAT rules in the database and update them.

Step 4: Updating the system configuration

Custom/override templates location

In eZ Publish versions prior to 4.0.0, the order of design resources used by the "ezdesign" and "ezimage" template operators was not the same as used by the "include" template function and eZTemplate::fetch(). This might lead to problems with overriding templates in extensions (refer to http://issues.ez.no/9595 for more information). This issue was fixed in eZ Publish 4.0.0.

In eZ Publish 4.0, templates that override default ones must be placed in the "override/templates" directory of your design. If you are not sure about the location of override templates in your eZ Publish installation, review the settings in your "override.ini.append.php" configuration file. (Refer to "The template override system" for more information.) The names of the override templates are specified using the "MatchFile" directive, which makes it possible to find the corresponding files on a filesystem.

Note that custom templates that are not connected with the override system must be placed in the "templates" directory of a custom design.

Outgoing mail delivery

In eZ Publish 4.0.0 there is a bug in the "ezsmtp" class that prevents the system from sending outgoing mails through an SMTP server. This bug will be fixed in the upcoming eZ Publish 4.0.1 release. If your site uses an SMTP relay server for mail delivery, you need to either switch to sendmail (if available) or download the updated version of the "ezsmtp" class and replace the corresponding file in your eZ Publish installation.

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 4.0 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. Without the "--purge" option, 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.