This section describes how to upgrade your existing eZ Publish 4.0.x installation to version 4.0.y. If you are upgrading from a version prior to eZ Publish 4.0.0, refer to the "Upgrading from 3.10.x to 4.0.y" section for upgrade instructions.

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.

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 4.0.1
2. Upgrading the database to 4.0.1
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 4.0.1 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"). Note that upgrading the distribution files will overwrite the autoload arrays for extensions. You will need to re-generate the autoload arrays for active extensions later (after enabling the "ezurlaliasmigration" extension in step 3).

If you are using the Website Interface front-end, be sure to copy the "extension/ezwebin/" directory.

Important bug fix for remote IDs

Due to some bugs in previous versions of eZ Publish (3.9.0 and others), it might happen that not all content objects in your database have unique remote IDs. This basically means that the "remote_id" column of the "ezcontentobject" table in the database might contain duplicate values. In eZ Publish 4.0.1, a database schema change was introduced in order to ensure that only unique remote IDs can be stored in this table. Because of this, you need to make sure that there are no content objects with identical remote IDs before upgrading the database. This can be done by running the "fixobjectremoteid.php" upgrade script. (Note that both the database schema change and the upgrade script were added to eZ Publish 3.9.5 and 3.10.1 as well.)

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.

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 update/common/scripts/4.0/fixobjectremoteid.php -s example
   

The script will search for objects with non-unique remote IDs. Every time such an object is found, the script will suggest to either display more detailed information or fix the problem automatically. If you choose the first option, the script will display the list of objects that have the same remote ID and let you decide which one should remain unchanged; all other objects in the list will get new remote IDs. Otherwise, the script will fix the problem automatically based on the objects' creation dates. This means that the script will generate new remote IDs for all objects in the list except the one that was created first.

The optional "--mode" parameter makes it possible to run the script in either "auto-fix" or "manual-fix" mode as shown below.

php update/common/scripts/4.0/fixobjectremoteid.php -s example --mode=value

If you replace "value" with "a" in the command above, the script will automatically fix all non-unique remote IDs that are found in the database based on the objects' creation dates. In this case, no further input is required from the user. If you specify "--mode=d", the script will display the list of objects for each non-unique remote ID so that you can manually choose which objects should keep their remote IDs.

Step 2: Upgrading the database

Follow the instructions below to upgrade your eZ Publish database from version 4.0.0 to 4.0.1.

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 the future, all database upgrade scripts will use the InnoDB storage engine when creating new tables. Because of this, 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.

You can use the "bin/php/ezconvertmysqltabletype.php" script to find out about the current storage engine in your database and convert your tables to use another engine if needed (refer to the "Switching to InnoDB" part of the "Upgrading from 3.10.x to 4.0.y" documentation page for more information about this script).

Running the database upgrade scripts

The following text describes how to run the database upgrade scripts. (Note that even though the sql file contains a section marked with "from 3.10.1" comments, you do not need to skip this part when upgrading from 4.0.0 to 4.0.1.)

MySQL

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

   mysql -u <username> -p<password> <database> < update/database/mysql/4.0/dbupdate-4.0.0-to-4.0.1.sql
   

PostgreSQL

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

   psql -d <database> -U <dbowner> < update/database/postgresql/4.0/dbupdate-4.0.0-to-4.0.1.sql
   

Specific steps for upgrading to versions 4.0.2 until 4.0.7 are located here.

Step 3: Running the system upgrade scripts

The 4.0.1 version of eZ Publish introduces a couple of important bug fixes and functionality changes. In order to make sure that your site is compatible with these changes, you may need to run a few upgrade scripts.

Multi-language support for URL aliases

In eZ Publish 4.0.1, the multi-language support for URL aliases was substantially improved, along with some important bug fixes related to this functionality. When upgrading, you need to regenerate all URL aliases that are stored in the "ezurlalias_ml" database table. This basically means that all auto-generated URL aliases will be deleted and then created from scratch by using the "updateniceurls.php" script. However, manual/user-defined URL aliases and URL history entries cannot be regenerated automatically. Instead, these items will be transfered/migrated into a temporary table in the database (hereinafter called "migration table") and then restored at a later stage. This must be done by using the "migrate.php" script, which is included in the "ezurlaliasmigration" extension. This new extension is included in eZ Publish 4.0.1 and provides tools for the purpose of URL alias migration.

Follow the instructions below in order to update your URL aliases.

1. Create a database backup.

Before you continue, create a backup of your database (or at least make sure that you have a backup of the "ezurlalias_ml" table itself).

2. Enable the "ezurlaliasmigration" extension.

The "ezurlaliasmigration" extension must be enabled for all of your siteaccesses. To do this, edit the "site.ini.append.php" file located in the "settings/override" directory and add the following line under the [ExtensionSettings] section:

ActiveExtensions[]=ezurlaliasmigration

Alternatively, you can enable the extension separately for each siteaccess. To do this, edit the "site.ini.append.php" file located in the "settings/siteaccess/example" directory (replace "example" with the name of the target siteaccess) and add the following line under the [ExtensionSettings] section:

ActiveAccessExtensions[]=ezurlaliasmigration

3. Update the autoload arrays for extensions (optional).

If you are using custom extensions, some of them might stop working after upgrading to 4.0.1. The reason for this is that the "autoload/ezp_extension.php" file is overwritten in the first step of the upgrade procedure (when upgrading the distribution files). To solve the problem, you need to regenerate the autoload arrays for active extensions as described below.

Note that the default "autoload/ezp_extension.php" file in eZ Publih 4.0.1 contains all the information needed for the following extensions to work correctly: "ezdhtml", "ezodf", "ezurlaliasmigration", "ezflow" and "ezwebin". If you are only using these extensions (no custom ones), you do not have to regenerate the autoload arrays when upgrading to 4.0.1.

The following example shows how to regenerate the autoload arrays for extensions.

1. Navigate into the eZ Publish 4.0.1 directory.
2. Run the script using the following shell command:

   php bin/php/ezpgenerateautoloads.php --extension
   

The script will look for class definitions in the "extension" directory and update the "autoload/ezp_extension.php" file accordingly.

Note that the command above makes the script go through all extensions regardless of whether or not they are enabled. You can also instruct the script to skip inactive extensions by listing them in the optional "--exclude" parameter (replace "ext1" and "ext2" with the actual names of the extension subdirectories):

php bin/php/ezpgenerateautoloads.php --extension --exclude="extension/ext1 extension/ext2"

4. Create the migration table.

The "ezurlaliasmigration" extension requires a custom database table called "ezurlalias_ml_migrate" to be created in the database. This table will be used for storing the migrated URL alias data. The new table must be created in accordance with the definitions specified in the "schema.sql" file included in the extension. This can be done by executing the SQL queries from the "schema.sql" file as described below.

If you are using MySQL, navigate into the eZ Publish 4.0.1 directory and run the following shell command:

mysql -u <username> -p<password> <database> < extension/ezurlaliasmigration/sql/mysql/schema.sql

If you are running PostgreSQL, use the following shell command instead:

psql -d <database> -U <dbowner> < extension/ezurlaliasmigration/sql/postgresql/schema.sql

Alternatively, you can use the "migrate.php" script to create the migration table. This option will work regardless of which database implementation you are using. You need to navigate into the eZ Publish 4.0.1 directory and run the script from within the system shell:

php extension/ezurlaliasmigration/scripts/migrate.php --create-migration-table

With this command, the script will create the "ezurlalias_ml_migrate" table 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:

php extension/ezurlaliasmigration/scripts/migrate.php -s example --create-migration-table

(Replace "example" with the actual name of your siteaccess.)

5. Transfer your URL aliases to the migration table.

To find out about the current number of manual/user-defined URL aliases and URL history entries in your system, run the "migrate.php" script without parameters or with the "-s" parameter only. The following example shows how this can be done.

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

   php extension/ezurlaliasmigration/scripts/migrate.php -s example
   

Note that the commands for running the "migrate.php" and "updateniceurls.php" scripts in the examples below will assume that all your siteaccesses share the same database. Because of this, the "-s example" part will be omitted and the scripts will be run for the database that is used by the default siteaccess. If you are using two or more databases, the "migrate.php" script should be run once for each database, specifying one siteaccess per database (by adding the "-s" parameter to each command). This also applies to the "updateniceurls.php" script. Both scripts need to be run from the root directory of your eZ Publish 4.0.1 installation. The following table reveals the available parameters for the "migrate.php" script.

To transfer your manual URL aliases and URL history entries into the migration table, run the "migrate.php" script as shown below:

php extension/ezurlaliasmigration/scripts/migrate.php --migrate

The script will go through all manual URL aliases and URL history entries in the "ezurlalias_ml" table and put the collected data into the "ezurlalias_ml_migrate" table.

Instead of transfering both manual URL aliases and URL history entries at once, it is also possible to run the script once for each type of URL entries. To do this, use either the "--migrate-alias" or "--migrate-history" parameter instead of "--migrate" when running the script (refer to the table above for more information about these parameters).

It is important not to change any configuration settings after transfering the data to the migration table. The configuration of the URL alias system must remain untouched until you're finished with regenerating the URL aliases and transfering the data back to the "ezurlalias_ml" table (otherwise, there might be some broken or inconsistent URLs on your site after upgrading to 4.0.1).

6. Remove old URL alias data.

Use the following SQL query to empty the "ezurlalias_ml" table in your database:

TRUNCATE ezurlalias_ml;

7. Create new auto-generated URL aliases.

Now that the "ezurlalias_ml" table is empty, you need to create new auto-generated URL aliases based on the existing node tree structure and content object names. When you do this, it is recommended that you clear ini cache first, in order to avoid using old settings from cache (This can be done in the administration interface). Then run the "updateniceurls.php" script using the following command:

php bin/php/updateniceurls.php --fetch-limit=number

Specify the desired number of items to handle per one iteration instead of "number". On a system with a 128 MB memory limit for PHP, this parameter can be set to 2000. (The script will automatically do as many iterations as necessary to generate the URL aliases for all nodes, based on the number specified. If the optional "--fetch-limit" parameter is omitted, the script will handle 200 items per one iteration.)

The script will go through all content objects stored in the database and create new virtual URLs for them in accordance with the current transformation settings. New URL aliases will be generated for all of the translation languages and placed in the "ezurlalias_ml" table in the database.

8. Restore migrated URL data.

You need to restore the custom URL aliases and URL history entries from the migration table. This can be done by running the "migrate.php" script:

php extension/ezurlaliasmigration/scripts/migrate.php --restore

The script will go through all entries in the "ezurlalias_ml_migrate" table and put the collected data back into the "ezurlalias_ml" table.

Instead of restoring both manual URL aliases and URL history entries at once, it is also possible to run the script once for each type of URL entries. To do this, use either the "--restore-alias" or "--restore-history" parameter instead of "--restore" when running the script (refer to the table above for more information about these parameters).

It might happen that a URL alias entry was previously corrupted and cannot be automatically restored from the migration table. In this case, you will see "F" in the console output of the "migrate.php" script. The following SQL query can be used in order to display the migrated entries that were not restored:

SELECT id, link, parent, lang_mask, text, action, is_original, is_alias, lang_mask_adjusted FROM ezurlalias_ml_migrate WHERE is_restored=0;

If you want the URL entries that were not restored automatically to work on your site, you must create new user-defined URLs later (when the upgrade procedure is finished). This can be done from within the administration interface as described on the "Managing URL aliases" documentation page.

Specific steps regarding URL alias upgrade when upgrading to version 4.0.2 is located here.

Changes to system upgrade scripts (optional)

If your solution was initially built on eZ Publish 3.10 or 4.0, skip this part. Otherwise, read it carefully.

The "updatevatcountries.php" upgrade script in eZ Publish 3.10.0 contains a bug. The same bug exists in eZ Publish 3.9.3 and 3.9.4 (refer to http://issues.ez.no/11955 for more information). The updated version of the script is available in eZ Publish 3.9.5, 3.10.1 and 4.0.1. If you previously upgraded to 3.10.0 using the original version of the script and then didn't run the updated version when upgrading from 3.10.0 to 4.0.0, you need to run it when upgrading to 4.0.1.

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.

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 update/common/scripts/4.0/updatevatcountries.php -s example
   

The script will go through all the VAT rules in the database and update them.

Step 4: Updating the system configuration

You are not required to do any configuration changes when upgrading from 4.0.x to 4.0.y.

Tree menu configuration (optional)

eZ Publish 4.0.1 introduces some changes to the dynamic tree menu functionality. In particular, the "treemenu" view of the "content" module no longer makes use of parameters that are transferred using GET variables (this improves tree menu compatibility when running PHP in FastCGI mode; refer to http://issues.ez.no/11806 for more information).

If you have instructed Apache to use "index_treemenu.php" instead of "index.php" when the treemenu view of the content module is requested, this feature will stop working after upgrading to version 4.0.1. To make it work, update your rewrite rules as described below.

If your ".htaccess" file contains the following line:

RewriteRule content/treemenu/?$ index_treemenu.php

you need to remove "$" from there. The updated line should look like this:

RewriteRule content/treemenu/? index_treemenu.php

If no ".htaccess" file is used, check whether the following line is present in your Apache configuration file:

RewriteRule content/treemenu/?$ /index_treemenu.php [L]

If found, remove "$" from this line. The result will look like this:

RewriteRule content/treemenu/? /index_treemenu.php [L]

Note that due to a bug in eZ Publish 4.0.1, you need to download the updated version of "index_treemenu.php" from http://pubsvn.ez.no and replace the corresponding file in your installation. The same bug exists in eZ Publish 3.10.1.

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

Upgrading to 4.0.2

URL Alias upgrade

The 4.0.2 release expands on the work which was made to the URL alias system in 4.0.1. The fix to the URL alias system, changes the structure in which URL entries are stored. This means that the URL alias entries needs to be regenerated, as was the case when upgrading to 4.0.1.

Follow the above upgrade steps to upgrade the URL aliases. With one important difference:

In the last round of fixes made in this area, we discovered that it is unfortunately not possible to migrate the URL alias history entries. This is because they cannot be restored properly. This means that in the migration process, the migrate.php script should be run with the options to migrate aliases only (custom aliases are retained, as well as all future history elements).

A simplified run down of the process below. Please advise with the full upgrade documentation for more detail.

• Migrate custom URL aliases

  php extension/ezurlaliasmigration/scripts/migrate.php --migrate-alias
  

• To clean up existing URL alias table, run this query:

  truncate ezurlalias_ml;
  

• Regenerate URL alias entries for the site access example, replace with your own value

  bin/php/updateniceurls.php -s example --fetch-limit=number
  

• Restore custom URL aliases

  php extension/ezurlaliasmigration/scripts/migrate.php --restore-alias
  

General upgrade scripts

First the database update queries need to be run. Then the upgrade scripts listed below, must be run. Use the -h parameter to see usage on how to run them.

• php update/common/scripts/4.0/initurlaliasmlid.php
  

• php update/common/scripts/4.0/fixezurlobjectlinks.php
  

• php update/common/scripts/4.0/fixclassremoteid.php
  

Upgrading to 4.0.3

If you are not upgrading from eZ Publish 4.0.2, first make sure that the upgrade steps for 4.0.2 are performed, as listed above. For upgrading from eZ Publish 4.0.2 to eZ Publish 4.0.3, only the database queries in dbupdate-4.0.2-to-4.0.3.sql are required.

Upgrading to 4.0.4

If you are not upgrading from eZ Publish 4.0.3, first make sure that the upgrade steps for 4.0.3 are performed, as listed above. For upgrading from eZ Publish 4.0.3 to eZ Publish 4.0.4, only the database queries in dbupdate-4.0.3-to-4.0.4.sql are required.

Upgrading to 4.0.5

If you are not upgrading from eZ Publish 4.0.4, first make sure that the upgrade steps for 4.0.4 are performed, as listed above. For upgrading from eZ Publish 4.0.4 to eZ Publish 4.0.5, only the database queries in dbupdate-4.0.4-to-4.0.5.sql are required.

Upgrading to 4.0.6

If you are not upgrading from eZ Publish 4.0.5, first make sure that the upgrade steps for 4.0.5 are performed, as listed above. For upgrading from eZ Publish 4.0.5 to eZ Publish 4.0.6, only the database queries in dbupdate-4.0.5-to-4.0.6.sql are required.

Upgrading to 4.0.7

If you are not upgrading from eZ Publish 4.0.6, first make sure that the upgrade steps for 4.0.6 are performed, as listed above. For upgrading from eZ Publish 4.0.6 to eZ Publish 4.0.7, only the database queries in dbupdate-4.0.6-to-4.0.7.sql are required.