This documentation page is deprecated and no longer maintained. Refer to the following documentation pages for upgrade instructions:

• Upgrading from 3.10.x to 4.0.y
• Upgrading from 4.0.x to 4.0.y

This section describes how to upgrade your existing eZ Publish 4.0.0 installation to version 4.0.1rc2 (hereinafter called "4.0.1" for the sake of simplicity).

Important note

Before continuing, note that eZ Publish 4.0.1 does not support migrating global URL aliases yet. This means that your global URL aliases (if any) will be lost after upgrading to 4.0.1rc2. You can check the list of global URL aliases in the "Setup - URL translator" part of the administration interface. If there are some items on the list, it is recommended to delay upgrading until the stable release of eZ Publish 4.0.1 is out. (Otherwise, you'll need to re-create all global URL aliases manually after upgrading to 4.0.1rc2.)

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 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 (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 old versions of eZ Publish (3.7.3 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 will be added to the upcoming versions 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

The following text describes how a 4.0.0 database can be upgraded to 4.0.1. (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
   

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

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.

Parameter	Description
--create-migration-table	Create the migration table in the database.
--migrate-alias	Transfer manual URL aliases to the migration table.
--migrate-history	Transfer URL history entries to the migration table.
--migrate	Transfer both manual URL aliases and URL history entries to the migration table.
--restore-alias	Restore manual URL aliases from the migration table.
--restore-history	Restore URL history entries from the migration table.
--restore	Restore both manual URL aliases and URL history entries from the migration table.

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. To do this, 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.

Note that the "migrate.php" script is currently unable to restore global URL aliases from the migration table (refer to http://issues.ez.no/13475 for more information). This issue will be fixed in the stable release of version 4.0.1.

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 4.0.1 (plus the upcoming versions 3.9.5 and 3.10.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.0 to 4.0.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.

---