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

Important note

Before continuing, note that it is recommended to upgrade directly to the latest stable release in the 3.8 branch, which is version 3.8.10. Refer to "Upgrading from 3.a.b to 3.x.y" and "Upgrading from 3.8.x to 3.8.y" to learn how this can be done. Note that there is a significant problem with eZ Publish 3.8.0-3.8.8. More precisely, the discount functionality of the shop module contains a security vulnerability. The issue has been fixed in version 3.8.9. Refer to the announcement and the upgrade instructions for details.

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.8.0
2. Upgrading the database to 3.8.0
3. Running the system 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.8.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.6.0 database can be upgraded to 3.8.0.

MySQL

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

   mysql -u <username> -p<password> <database> < update/database/mysql/3.8/dbupdate-3.6.0-to-3.8.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.8.0 directory.
2. Run the database upgrade script:

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

Step 3: Running the system upgrade scripts

The 3.8.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.

Improved multi-language functionality

The 3.8.0 version of eZ Publish introduces improved multi-language functionality. In order to make sure that your site is compatible with this new feature, you will have to update the configuration settings and run the "updatemultilingual.php" script. This step must be done even though your site has only one language.

Configuring languages

Before running the upgrade script you need to configure how the languages must be displayed on your site.

For the public siteaccess(es) where only specific languages should be shown, add the following lines into the "[RegionalSettings]" section of the "settings/siteaccess/example/site.ini.append.php" file (replace "example" with the actual name of the siteaccess):

SiteLanguageList[]
SiteLanguageList[]=<my-first-language>
SiteLanguageList[]=<my-second-language>
ShowUntranslatedObjects=disabled

e.g. for British English and German languages you would do:

SiteLanguageList[]
SiteLanguageList[]=eng-GB
SiteLanguageList[]=ger-DE
ShowUntranslatedObjects=disabled

This will tell the system that English has the highest priority and German is the second language. Any other languages will not be shown.

For the siteaccess(es) like administration interface where all languages should be shown, add the following lines into the "[RegionalSettings]" section of the "settings/example_admin/site.ini.append.php" file (replace "example_admin" with the actual name of the siteaccess):

SiteLanguageList[]
SiteLanguageList[]=<my-first-language>
SiteLanguageList[]=<my-second-language>
ShowUntranslatedObjects=enabled

e.g. for British English and German languages you would do:

SiteLanguageList[]
SiteLanguageList[]=eng-GB
SiteLanguageList[]=ger-DE
ShowUntranslatedObjects=enabled

This will tell the system that English has the highest priority and German is the second language. All other languages will still be shown (and editable) but will have less priority. The "ShowUntranslatedObjects" setting controls whether all languages are shown or not.

Running the upgrade script

The "updatemultilingual.php" 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 the siteaccess isn't specified, the default siteaccess will be used. Note that you will need to either publish or remove all the unpublished drafts in your system before launching this script.

The following example shows how to run the script:

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

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

It is strongly recommended to read the information the script provides before continuing. If unsure press Control + C on your keyboard while the shell/console is active.

RSS import enhancements (optional)

The 3.8.0 version of eZ Publish introduces more generic RSS import that allows using custom RSS import definitions. If you are using the RSS import functionality on your site, you will have to run the "updaterssimport.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 the siteaccess isn't specified, the default siteaccess will be used.

The following text shows how this can be done.

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

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

Step 4: Updating the system configuration

Treemenu configuration

In eZ Publish 3.8, the default configuration for the left treemenu in the administration interface has changed i.e. only folder, forum, gallery and user group objects are visible in the menu by default. (In previous versions, objects of any class were shown in the treemenu and this could cause problems when the number of objects in the system increased.)

The classes that the visible objects belong to are determined by the "ShowClasses[]" array located under the "[TreeMenu]" section of the "settings/contentstructuremenu.ini" configuration file. The following configuration is used by default:

[TreeMenu]
ShowClasses[]
ShowClasses[]=folder
ShowClasses[]=forum
ShowClasses[]=gallery
ShowClasses[]=user_group

If you want to display other objects in the treemenu, e.g. user and article objects, do the following:

1. Open the "contentstructuremenu.ini.append.php" configuration file located in the "settings/override" or "settings/siteaccess/example_admin" directory (replace "example_admin" with the actual name of your admin siteaccess) and edit it. If the file does not exist, create it.
2. Add the following lines under the "[TreeMenu]" section:

   [TreeMenu]
   ShowClasses[]=user
   ShowClasses[]=article
   

   where "user" and "article" are class identifiers.

It is possible (but not recommended) to make the treemenu showing objects of all classes as in previous versions of eZ Publish. To do this, use the following configuration in the "contentstructuremenu.ini.append.php" file:

[TreeMenu]
ShowClasses[]

Binary files indexing configuration

In eZ Publish versions prior to 3.8.0, the following default settings for binary file indexing were specified in the "binaryfile.ini" configuration file:

[HandlerSettings]
MetaDataExtractor[text/plain]=plaintext
MetaDataExtractor[application/pdf]=pdf
MetaDataExtractor[application/msword]=word

In eZ Publish 3.8.0, the default settings for binary file indexing have been changed. This is how the new settings look like:

[HandlerSettings]
MetaDataExtractor[text/plain]=ezplaintext
MetaDataExtractor[application/pdf]=ezpdf
MetaDataExtractor[application/msword]=ezword

If you have overridden these settings in your "binaryfile.ini.append.php" then you need to review your settings.

Default configuration of unique user emails

In eZ Publish versions prior to 3.8.0, the default configuration does not allow different users to be registered with the exact same email address. This is just a built-in precaution mechanism which can be easily turned off by setting the "RequireUniqueEmail" directive within the [UserSettings] block of a configuration override for "site.ini" to "false". However, this default configuration has been accidentally changed in eZ Publish version 3.8.0 (refer to http://issues.ez.no/9643 for more information). The change is reverted in eZ Publish version 3.8.7. If you are going to use eZ Publish 3.8.0-3.8.6, it is recommended to add the following line to the [UserSettings] block of the "override/site.ini.append.php" configuration file:

RequireUniqueEmail=true

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