This section describes how to upgrade your existing eZ Publish 3.8.x installation to version 3.9.0. If you are upgrading from a version prior to eZ Publish 3.8.0, you need to first upgrade to 3.8.0 before you can upgrade to 3.9.0.

Important note

Before continuing, note that it is recommended to upgrade directly to the latest stable release in the 3.9 branch. (Refer to "Upgrading from 3.a.b to 3.x.y" and "Upgrading from 3.9.x to 3.9.y" to learn how this can be done.) Mainly, there are two reasons for this:

• The "correctxmltext.php" upgrade script in eZ Publish 3.9.0 contains a bug. It makes the script crash. This issue was fixed in 3.9.1. Refer to http://issues.ez.no/9952 for more information.
• 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 issue has been fixed in version 3.9.3. Refer to the announcement and the upgrade instructions for details.

Overview

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.0
2. Upgrading the database to 3.9.0
3. Running the 3.9.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 3.9.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 (for example the "PayPal" extension).

Step 2: Upgrading the database

The following text describes how a 3.8.0 database can be upgraded to 3.9.0. Before reading on, note that some of the database changes from eZ Publish 3.8.0 to 3.9.0 have been included in eZ Publish versions 3.8.1 and 3.8.5 as well. If you are upgrading from a version later than 3.8.0, it is recommended to skip some parts of the database upgrade scripts (the sections that should be skipped are marked with "from 3.8.1" or "from 3.8.5" comments in the ".sql" file).

MySQL

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

   mysql -u <username> -p<password> <database> < update/database/mysql/3.9/dbupdate-3.8.0-to-3.9.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 (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 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 tables to InnoDB using the following SQL queries:

ALTER TABLE ezcontentobject_trash TYPE = innodb;
ALTER TABLE ezcontentclass_name TYPE = innodb;
ALTER TABLE ezsearch_search_phrase TYPE = innodb;
ALTER TABLE ezsearch_return_count 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.9.0 directory.
2. Run the database upgrade script:

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

Step 3: Running the 3.9.0 upgrade scripts

The 3.9.0 version of eZ Publish introduces a couple of new features. In order to make sure that your site is compatible with these features, you'll have to run a couple of upgrade scripts.

Translating names of classes and class attributes

In eZ Publish 3.9, a new feature has been added to the multi-language functionality that makes it possible to translate names of the eZ Publish content classes / class attributes (see this page for more information). In order to make sure that your site is compatible with this new functionality, you will have to run the "updateclasstranslations.php" script. This step must be done even though your site has only one language.

The "updateclasstranslations.php" script should be run for all siteaccesses that use different databases. It is strongly recommended that you only run the script once per database, otherwise your class and attribute names may be corrupted. If you only have a public and an administration siteaccess (which is the most typical/usual case), you will only need to run the script for one of the siteaccesses.

The "language" parameter tells the script which language your class / class attribute names currently exist in. Note that only one language can be specified using this parameter. If your classes are in different languages, it is recommended to specify the language that is used for most of them (for example, if 10 default class names are in English and 2 names of newly created custom classes are in Norwegian, you should use English as a parameter for the script and then edit the two custom classes manually). The following example shows how to run the script.

1. Navigate into the eZ Publish 3.9.0 directory.
2. Run the script (replace "example" with the actual name of your siteaccess, specify the original language instead of "eng-GB"):

   php update/common/scripts/3.9/updateclasstranslations.php -s example --language=eng-GB
   

The script will check your content classes and content class attributes and re-initialize their names for missing translations.

Custom attributes for XML tags

eZ Publish 3.9.0 supports using custom attributes in all XML tags (see this page for more information). The names of the custom attributes must be added to the global (or siteaccess) "content.ini.append.php" configuration file. For example, if you wish to use a specific summary field in your tables, you can add a custom attribute called "summary" to the "table" XML tag by adding the following lines to the [table] section of your "content.ini.append.php" file:

CustomAttributes[]
CustomAttributes[]=summary

In order to be compatible with this new feature, you will have to run the "correctxmltext.php" script. The following example shows how this can be done.

1. Navigate into the eZ Publish 3.9.0 directory.
2. If all your siteaccesses are using the same database, run the script with the "--global" option so that it will only update the "settings/override/content.ini.append.php" file:

   php update/common/scripts/3.9/correctxmltext.php --global
   

   Otherwise, run the script for each of your siteaccesses (replace "example" with the actual name of your siteaccess):

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

Use "--help" to view the additional options supported by this script.

Note that this script is faulty. Refer to http://issues.ez.no/9952 for more information about the problem and the solution.

The script will go through the XML block attributes stored in the database and do the following:

• Find all occurrences of the "object" tags (if any) and convert these to "embed" tags. (The "object" tag is deprecated and no longer used.)
• Check which custom classes are used within your XML tags and add missing "AvailableClasses[]" settings to your configuration file. (From 3.8.1, the names of all custom classes that are used within XML tags must be specified from within an override of the "content.ini" configuration file.)
• Check which custom attributes are used in your XML tags and add missing "CustomAttributes[]" settings (if any) to your configuration file.

Note that you can skip some of these tasks by using one of the options listed below:

If you do not wish to update your configuration file automatically, run the script like this:

php update/common/scripts/3.9/correctxmltext.php --classes-dump-only --custom-dump-only

The "--classes-dump-only" option allows you to view the list of missing classes instead of having your "AvailableClasses[]" settings automatically updated. The "--custom-dump-only" option allows to view the list of missing custom attributes without modifying the "CustomAttributes[]" settings.

Enhanced object relations

In eZ Publish 3.9.0, the object relations functionality has been improved (see this page for more information). The system will now use four types of object relations called "common", "XML linked", "XML embedded" and "by attribute". The first three types are relations at the object level while the last one is at the attribute level. The "XML embedded" type has been added in order to distinguish object relations created by inserting an embedded object in the XML block attribute from relations created by adding an object to the list of related objects (this type of relations is now called "common"). The "XML linked" type is used for new relations that are automatically created by the system when an internal link is inserted in an attribute of the XML block datatype. Note that "XML linked" relations are automatically removed when corresponding internal links are deleted. Same goes for "XML embedded" relations and their "embed" tags.

In order to be compatible with this new feature, you will have to run the "updatetypedrelation.php" script. 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 will only need to run the script for one of the siteaccesses. If the siteaccess is not specified, the default siteaccess will be used.

The following text shows how this can be done.

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

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

The script will go through the XML block attributes stored in the database and create object relations of the "XML linked" and "XML embedded" types if needed.

Step 4: Updating the system configuration

Updating INI settings for object relations

After running the upgrade scripts listed above you will need to configure how the object relations of the "XML linked" type will be handled on your site. From 3.9.0, inserting an internal link in the XML block attribute will lead to adding an "XML linked" relation. This behavior is controlled by the "ObjectRelationTyped" setting located in the "[BackwardCompatibilitySettings]" section of the "site.ini" configuration file. If you do not wish to use the "XML linked" type of relationships, make sure this setting is disabled.

Updating custom templates (optional)

In eZ Publish versions prior to 3.9, the "$node" variable might be present in the pagelayout when view caching is disabled. From 3.9, the "$node" variable is only available in node templates. This means that you will not be able to use this variable in the pagelayout (and other templates that are not related to the "view" view of the "content" module) even if view caching is disabled.

Enabling the Open Document Format extension (optional)

eZ Publish 3.9 includes the Open Document Format extension (previously known as "oo" and the "OpenOffice extension"). In order to use this extension, make sure your "settings/override/site.ini.append.php" file contains the following lines:

[ExtensionSettings]
ActiveExtensions[]=ezodf

Note that it is also possible to enable this extension using the "Setup - Extensions" part of the administration interface as described here.

Updating INI settings for cronjobs (optional)

In eZ Publish 3.9.0, the default configuration of cronjobs has changed. The main set of cronjobs only contains tasks that should be run once a day. The tasks that should be executed frequently (workflow.php and notification.php) are now included in an additional set of cronjobs called "frequent". One more additional group of cronjobs called "infrequent" contains tasks that can be run once a week (linkcheck.php and basket_cleanup.php). The "ezpublish.cron" file is also updated. It is recommended to review your cronjob settings after upgrading.

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