This section describes how to upgrade your existing eZ Publish 3.10.x installation to version 4.0.y. If you are upgrading from version 3.10.0 or earlier, you need to first upgrade to 3.10.1 before you can upgrade to 4.0. (Refer to either "Upgrading from 3.9.x to 3.10.y" or "Upgrading from 3.10.x to 3.10.y" depending on which version you are currently running.)

In order to benefit from the latest bug fixes, you should upgrade directly to the latest stable release in the 4.0 branch (4.0.1 at the time of writing). Refer to the changelogs and security advisories for more information about the issues that were fixed in the latest releases. Note that there is a significant problem with eZ Publish 4.0.0. More precisely, the "ezsmtp" class contains a bug that prevents the system from sending outgoing mails through an SMTP server. This bug was fixed in version 4.0.1.

Note that in some cases, it is not possible or not recommended to upgrade from 3.10 to 4.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).

Make sure that you have a working backup of the site before you do the actual upgrade.

The procedure for upgrading directly from version 3.10.x to 4.0.y consists of the following steps:

1. Upgrading the distribution files to 4.0.y
2. Upgrading the database to 4.0.y
3. Running the system upgrade scripts for versions from 3.10.x to 4.0.y
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.y to a separate 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" and "ezurlaliasmigration").

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 to upgrade your eZ Publish database from version 3.10.x to 4.0.y.

Switching to UTF-8

eZ Publish 4 requires UTF-8 as the character set. If your site makes use of another character set, you must switch to UTF-8. To find out about the current character set in your database, you can run the following command using the MySQL command-line tool (replace "db_name" with the actual name of your database):

mysql> SHOW CREATE DATABASE db_name;

PostgreSQL users can view the list of available databases along with their character sets by running the following command from within the system shell:

psql -l

In eZ Publish 4.0.1, the "bin/php/ezconvertdbcharset.php" script was added in order to convert databases to use UTF-8. (Refer to the developer documentation for more information and troubleshooting tips).

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.

Before running the script, make sure that eZ Publish knows the current character set in the database. Basically, the script will rely on the "Charset" setting located in the "[DatabaseSettings]" section of "settings/override/site.ini.append.php" or "settings/siteaccess/<your_siteacess>/site.ini.append.php". If this setting is empty, the value of the "Charset" setting located in the [CharacterSettings] section of "i18n.ini" (or an override) will be used.

The following example shows how to run the script:

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

   php bin/php/ezconvertdbcharset.php -s example
   

The script will convert the database to use UTF-8 as the character set. After running the script, make sure that eZ Publish knows about the database's new character, and also update the eZ Publish internal character set accordingly, in the correct override files:

• File: "site.ini":

[DatabaseSettings]
 Charset=utf-8

• File: "i18n.ini":

[CharacterSettings]
Charset=utf-8

Switching to InnoDB (MySQL only)

If you are using MySQL, note that the recommended storage engine is InnoDB. This storage engine is used by default during the installation process when the setup wizard initializes the database structure for eZ Publish. In addition, InnoDB will most likely be required for future versions of eZ Publish to run on MySQL. Contact your database administrator if you are unsure about whether InnoDB is available on your server.

In eZ Publish 4.0.1, the database upgrade scripts use the InnoDB storage engine when creating new tables. Before running these scripts, it is recommended (but not required) to make sure that all existing tables in your database use InnoDB. If you want to use the MyISAM (or another) storage engine instead, all existing tables in your database must use this engine. In addition, you will have to replace "InnoDB" with "MyISAM" in the database upgrade scripts before running them. Read the following text for more detailed instructions.

To find out about the current storage engine in your database, navigate into the eZ Publish directory and run the "bin/php/ezconvertmysqltabletype.php" script with the "--list" parameter:

php bin/php/ezconvertmysqltabletype.php --list

The script will output the list of tables in the database along with the name of the storage engine for each table.

With the command above, the script will check the table types in the database that is used by the default siteaccess. If your site makes use of two or more databases, you need to run the script once for each database, specifying one siteaccess per database. Use the "-s" parameter to specify the target siteaccess as shown below (replace "example" with the actual name of your siteaccess):

php bin/php/ezconvertmysqltabletype.php --list -s example

If all tables in your eZ Publish database use the InnoDB storage engine, no changes are needed. If some tables use MyISAM or another storage engine, it is recommended (but not required) to convert them to InnoDB. To do this, run the script with the "--newtype" parameter as shown below:

php bin/php/ezconvertmysqltabletype.php --newtype=innodb -s example

The script will convert all tables in your database to InnoDB. Note that the script will automatically skip the tables that already use the InnoDB storage engine from before (if any).

You can also convert tables individually by using the following SQL query for each table:

ALTER TABLE <name_of_table> TYPE = innodb;

If you wish to use a storage engine other than InnoDB, make sure that all tables in your database use this engine. In addition, you will have to change the engine specified in the first line of the database upgrade scripts before running them (otherwise, the upgrade will leave you with a mix of table types).

You will find the database upgrade scripts in the "update/database/mysql/4.0/" directory. Each database upgrade script that creates new tables contains the following line in the beginning:

SET storage_engine=INNODB;

Before you run such a script, replace "INNODB" with the name of your storage engine. For example, if all existing tables in your database use MyISAM, you need to modify the first line as shown below:

SET storage_engine=MYISAM;

This will make the database upgrade script use MyISAM instead of InnoDB when creating new tables.

Running the database upgrade scripts

To upgrade your database from version 3.10.1 to 4.0.1, you need to navigate into the eZ Publish 4.0.1 directory and run the following database upgrade scripts one after another:

1. dbupdate-3.10.0-to-4.0.0.sql
2. dbupdate-4.0.0-to-4.0.1.sql

Note that some of the database changes from eZ Publish 3.10.0 to 4.0.1 have been included in the 3.10.1 release as well. This means that you need to skip some parts of the database upgrade scripts when upgrading from version 3.10.1 to 4.0.1. These are marked with "from 3.10.1" comments in the ".sql" files.

MySQL

The database upgrade scripts are located in the "update/database/mysql/4.0/" directory of your eZ Publish installation. Each of these scripts can be launched using the following shell command (replace "script_name" with the actual name of the script):

mysql -u <username> -p<password> <database> <
update/database/mysql/4.0/script_name.sql

PostgreSQL

The database upgrade scripts are located in the "update/database/postgresql/4.0/" directory of your eZ Publish installation. Each of these scripts can be launched using the following shell command (replace "script_name" with the actual name of the script):

psql -d <database> -U <dbowner> < update/database/mysql/4.0/script_name.sql

Step 3: Running the system upgrade scripts

You are not required to run any system upgrade scripts when upgrading from 3.10.1 to 4.0.1.

Step 4: Updating the system configuration

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, 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.

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. When the "--purge" parameter is not specified, the caches will be expired but not removed (refer to this page for more information).

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