This section describes how to upgrade your existing eZ Publish 3.5.2 installation to version 3.7.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.7.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.7.0
2. Upgrading the database to 3.7.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.7.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.7.0.

MySQL

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

   mysql -u <username> -p<password> <database> < update/database/mysql/3.6/dbupdate-3.5.2-to-3.6.0.sql
   

3. Run the second database upgrade script:

   mysql -u <username> -p<password> <database> < update/database/mysql/3.7/dbupdate-3.6.0-to-3.7.0.sql
   

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

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

3. Run the second database upgrade script:

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

Step 3: Running the 3.6.0 upgrade scripts

The 3.6.0 version of eZ Publish introduced a couple of new features that are used in 3.7 version also. In order to make sure that your site is compatible with these features, 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.

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

   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.7.0 directory.
2. Run the script (replace <siteaccess> with the name of your siteaccess(es)):
   

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

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.

Enabling database transaction support (optional)

eZ Publish 3.6.0 introduced 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.7.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.7.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.