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

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.6.0
2. Upgrading the database to 3.6.0
3. Running the 3.6.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.6.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 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

The following text describes how a 3.5.2 database can be upgraded to 3.6.0.

MySQL

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

   mysql -u <username> -p<password> <database> < update/database/mysql/3.6/dbupdate-3.5.2-to-3.6.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 use the "bin/php/ezconvertmysqltabletype.php" script for database conversion. It is also possible to convert the newly created tables to InnoDB using ALTER TABLE statements as shown in the following example:

ALTER TABLE table_name1 TYPE = innodb;
ALTER TABLE table_name2 TYPE = innodb;
...

Replace "table_name1", "table_name2" with the actual names of the tables that need to be converted.

PostgreSQL

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

   psql -d <database> -U <dbowner> < update/database/postgresql/3.6/dbupdate-3.5.2-to-3.6.0.sql
   

Step 3: Running the 3.6.0 upgrade scripts

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

Internal linking

In order to be compatible with the new internal linking feature, you will have to run the "convertxmllinks.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), then you will only need to run the script for one of the siteaccesses. If you do not specify any siteaccess when running the script, then the default siteaccess will be used.

1. Navigate into the eZ Publish 3.6.0 directory.
2. Run the script for your default siteaccess:

   php update/common/scripts/convertxmllinks.php
   

   or use the following command to run the script for a specific siteaccess (replace <siteaccess> with the name of your siteaccess):

   php update/common/scripts/convertxmllinks.php -s <siteaccess>
   

Advanced related objects

In order to be compatible with the new advanced related objects feature, you will have to run the "updaterelatedobjectslinks.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), then you will only need to run the script for one of the siteaccesses.

1. Navigate into the eZ Publish 3.6.0 directory.
2. Run the script (replace <siteaccess> with the name of your siteaccess(es)):
   

   php update/common/scripts/updaterelatedobjectslinks.php -s <siteaccess>
   

Converting the "eztime" attributes

In eZ Publish 3.5.3 and 3.6.0, the "Time" datatype has been modified in order to make it possible to interpret the value of hours and minutes properly and independently from DST and GMT transformations (see the feature doc for more information). When upgrading from 3.5.2, you need to run the "updateeztimetype.php" script in order to convert the attributes of the "eztime" datatype from GMT to the server local time (replace "example" with the name of the siteaccess):

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

It is recommended to create a database backup before using this script. The script must be run for each siteaccess. Note that there is no need to run this script when upgrading from 3.5.3 or later.

Step 4: Updating the system configuration

Administration interface toolbar changes

The right section of the administration interface has been slightly changed in 3.6.0. It now uses the toolbar system and features a couple of new toolbars for developers (clear cache, debug control, etc.). In order to make it work, you will have to add the following settings in "toolbar.ini.append.php" for the siteaccesses that use the admin design:

[Toolbar]
AvailableToolBarArray[]=admin_right
AvailableToolBarArray[]=admin_developer
 
[Tool]
AvailableToolArray[]=admin_current_user
AvailableToolArray[]=admin_bookmarks
AvailableToolArray[]=admin_clear_cache
AvailableToolArray[]=admin_quick_settings
 
[Toolbar_admin_right]
Tool[]
Tool[]=admin_current_user
Tool[]=admin_bookmarks
 
[Toolbar_admin_developer]
Tool[]
Tool[]=admin_clear_cache
Tool[]=admin_quick_settings

Visibility of hidden nodes

In eZ Publish 3.6.0, the default value of the "ShowHiddenNodes" configuration directive has become "false". This means that hidden nodes will not be available on any siteaccess. It is recommended to add the following line to the "[SiteAccessSettings]" section of the "settings/siteaccess/example_admin/site.ini.append.php" configuration file (replace "example_admin" by the actual name of your admin siteaccess):

ShowHiddenNodes=true

This will instruct the system to show hidden nodes in the administration interface.

XML tag changes

From 3.6, the "object" XML tag is deprecated (but not removed because of backwards compatibility) and you should use the new "embed" tag for object embedding. The Online Editor automatically converts "object" tags to "embed" but this may cause problems with custom classes. To fix this, check whether your "content.ini.append.php" configuration file contains custom classes for the "object" tag. If yes, specify the same custom classes for the "embed" tag.

Note that if you use alternate/custom templates for rendering the content of XML tags, you will probably need to add one more template for "embed".

Example 1

Let's say that you have the following lines in an override of the "settings/content.ini" configuration file:

[object]
AvailableClasses[]=imageRed
AvailableClasses[]=imageBlue

If you are going to use the new "embed" tag, then you should add the following lines to the same file:

[embed]
AvailableClasses[]=imageRed
AvailableClasses[]=imageBlue

Example 2

If you have a custom template called "object.tpl" inside the "templates/content/datatype/view/ezxmltags/" subdirectory of your design, then you should add a new template called "embed.tpl" to the same directory.

Example 3

Let's say that your siteaccess "override.ini.append.php" file contains the following lines:

[imageRed_object]
Source=content/datatype/view/ezxmltags/object.tpl
MatchFile=imageRed_object.tpl
Subdir=templates
Match[classification]=imageRed

This means that all images classified as "imageRed" are rendered using the "imageRed_object.tpl" template located inside the "override/templates/" directory of your design. Since images will be inserted using the "embed" tag, you will have to override the "content/datatype/view/ezxmltags/embed.tpl" template in the same way.

Enabling database transaction support (optional)

eZ Publish 3.6.0 introduces support for database transactions. This feature makes eZ Publish less vulnerable for database errors and inconsistencies due to aborted requests. It is highly recommended to make use of this feature. Transaction support is available for MySQL from version 4.1 and above and for all PostgreSQL and Oracle versions. MySQL users must first convert the database (see below).

MySQL table conversion

MySQL users have to perform an extra step when enabling transaction support. Make sure that you have MySQL 4.0 or later before attempting to perform this step. Previous versions of eZ Publish use "MyISAM" type tables. Such tables do not support transactions. The database must be converted so that all tables use the "InnoDB" type instead of "MyISAM". This can be done using the "ezconvertmysqltabletype.php" script:

1. Navigate into the eZ Publish 3.6.0 directory.
2. Run the database conversion script; example:
   

   bin/php/ezconvertmysqltabletype.php --host=localhost --user=arnold --password=secret --database=ezpublish --newtype=innodb
   

   (You will have to provide your own values for the "host", "user", "password" and "database" parameters.)

It is also recommended to set the default storage engine to InnoDB (refer to MySQL documentation for information about how this can be done).

Enabling transaction support in eZ Publish

Each siteaccess which is configured to communicate with a database that uses "InnoDB" tables can be configured to use transactions. This can be done by adding "Transactions=enabled" within the "[DatabaseSettings]" block in "site.ini.append.php" for the target siteaccess(es). You can also add this line to the "settings/override/site.ini.append.php" file instead of doing it for each of the target siteaccesses (this way is recommended if all your siteaccesses use the same database).

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