This section describes how to upgrade your existing eZ Publish 4.7 installation to version 5.1. Make sure that you have a working backup of the site before you do the actual upgrade, and make sure that the installation you are performing the upgrade on is offline.

Note on Paths:

• /<ezp5-root>/: The root directory where eZ Publish 5 is installed in, examples: "/home/myuser/www/" or "/var/sites/ezpublish/"
• /<ezp5-root>/ezpublish_legacy/: Root directory of "Legacy" (aka "Legacy Stack", refers to the eZ Publish 4.x installation which is bundled with eZ Publish 5) normally inside "ezpublish_legacy/", example: "/home/myuser/www/ezpublish_legacy/"

Important upgrade notes:

Before starting, please make sure that the DebugByUser legacy setting is disabled, as it will interfere with the login mechanism. This is a known issue, and you can get more details and the fix itself in the related Jira, EZP-21237.
If you still need to use the debug by user feature, make sure to apply the patch from EZP-21237 or request for an official patch from the customer support team, until the fix is not yet distributed in a service pack.

The procedure for upgrading directly from version 4.7 to 5.1 consists of the following steps:

1. Upgrade the distribution files
2. Upgrade custom extensions
3. Upgrade the database
4. Run scripts
5. Regenerate the autoload array for extensions
6. Generate eZ Publish 5 yml configuration & symlink assets5
7. Fix images outside the var dir
8. Clear the caches
9. Update rewrite rules
10. Upgrade extensions (site package)

Check for requirements

php 5.3.3 and higher is needed. Further information regarding system requirements can be found on Requirements Documentation Page.

Step 1: Upgrade the distribution files

The easiest way to upgrade the distribution files is to unpack eZ Publish 5.1 to a separate directory and then copy the directories that contain site-specific files from the existing 4.7 installation into "/<ezp5-root>/ezpublish_legacy/". Make sure 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 site accesses, however make sure that you do not overwrite any designs that are included in eZ Publish distribution: admin, base, standard, mysite & plain, and avoid coping admin2 design as it has been merged into admin as of 5.0.

Note: Because the new directory has replaced the original directory, the directory permissions need to be fixed. You can choose between Shell commands or Alternative shell commands.

Use one of the following two alternatives to do this:

• Shell commands

These shell commands will give proper permission to the web server and command line users:

cd /<ezp5-root>/
chmod -R a+rwx ezpublish/{cache,logs,config} \
    ezpublish_legacy/{design,extension,settings,var}

• Recommended shell commands using setfacl

These commands will setup the permission more correctly, but require use of setfacl which is not available on all systems (change 'www-data' to your web server user if your system uses something else):

cd /<ezp5-root>/
sudo setfacl -R -m u:www-data:rwx -m u:www-data:rwx \
    ezpublish/{cache,logs,config} \
    ezpublish_legacy/{design,extension,settings,var}
sudo setfacl -dR -m u:www-data:rwx -m u:`whoami`:rwx \
    ezpublish/{cache,logs,config} \
    ezpublish_legacy/{design,extension,settings,var}

Cluster environments

For cluster environments the config.php from the legacy folder must be used as reference.
In a clean installation you can find it at the path ezpublish_legacy/config.php-RECOMMENDED.
Copy the file and configure it as desired. More retails can be found in the Setting it up for an eZDFSFileHandler document, in the step 3.

Also, please be aware that the eZDB file handler has been discontinued, and doesn't make part of eZ Publish 5.1 or higher versions. If you were using eZDB in your eZ Publish 4.7 installation you will need to uninstall the eZDB cluster. You can use eZDFS instead, which you can install by following the Setting it up for an eZDFSFileHandler tutorial.

Note: Be aware that memcache needs to be used on cluster environments. Please refer to the documentation on confluence for more details about memcache and usage example.

If using FS2 file handler

If you were using eZFS2 in your eZ Publish 4.7 installation, please be aware that the eZFS2 file handler has been discontinued, and doesn't make part of eZ Publish 5.1 or higher versions. eZFS file handler will be used instead.
For that you will need to edit your file.ini.append.php and change the FileHandler setting ,under the [ClusteringSettings] settings block, from eZFS2FileHandler to eZFSFileHandler. You can find an example below:

[ClusteringSettings]
 
FileHandler=eZFSFileHandler

Step 2: Upgrade custom extensions

If you are using custom extensions, the sub-directories inside the "extension" directory will also have to be copied from the existing 4.7 installation into "/<ezp5-root>/ezpublish_legacy/extension/". However, make sure that you do not overwrite any extensions that are included in eZ Publish distribution, which currently are (Note: As of eZ Publish 5.0, these extensions have the same version number as eZ Publish):

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.

Important: If you plan to upgrade your eZ Website Interface, eZ Flow or eZ Demo site package as well, then additional extensions will be updated and the step for re-generate the autoload arrays can be skipped until that is done (links to documentation for upgrading these site packages can be found in the last step of this page).

Step 3: Upgrade the database

The update scripts for the database is located in:

/<ezp5-root>/ezpublish_legacy/update/database/<mysql|postgresql>/5.0/dbupdate-4.7.0-to-5.0.0.sql
/<ezp5-root>/ezpublish_legacy/update/database/<mysql|postgresql>/5.1/dbupdate-5.0.0-to-5.1.0.sql

You can run these with the appropriate command line tool or application.

Step 4: Run scripts

The following script has to be run after the upgrade of the database:

cd /<ezp5-root>/ezpublish_legacy/
php update/common/scripts/5.0/deduplicatecontentstategrouplanguage.php

The following script must be executed to fix existing content and restore its relations. 

Note: This fix is about a known issue with relations and embedded/linked objects in XML text blocks that could be lost at object level for secondary languages and only applies to multilingual websites.

php update/common/scripts/5.0/restorexmlrelations.php

The following script is responsible for disabling user accounts with suspicious user login (containing < and >). Remove the '--disable' option for a dry run:

php update/common/scripts/5.0/disablesuspicioususers.php --disable

Note: If you are running ezxmlexport, an ezxmlexport upgrade SQL script have to be imported. The scripts for each supported database are available in /<ezp5-root>/ezpublish_legacy/extension/ezxmlexport/update/database/[your database]/5.0/dbupdate-1.5-5.0.sql.

Step 5: Regenerate the autoload array for extensions

To regenerate the autoload array, execute the following script from the root of your eZ Publish Legacy directory:

cd /<ezp5-root>/ezpublish_legacy/
php bin/php/ezpgenerateautoloads.php --extension

Step 6: Generate eZ Publish 5 yml configuration & symlink assets

yml config

Note: This command will wipe out all custom yml config on subsequent runs, make sure to use "--backup" parameter if you run this command several times.

To generate yml configuration for the new Symfony stack, a console command has been provided to cover single site setups.

Perform the following command where `<group>` is the siteaccess group name(new concept, a grouping of siteaccesses that have something in common, db and admin siteaccess would be minimum determinators to be able to use the command), examples of group name: 'ezdemo_site', 'ezwebin_site' or 'ezflow_site'. And `<admin_siteaccess>` is the name of the admin siteaccess, for instance, 'ezdemo_site_admin'.

cd /<ezp5-root>
php ezpublish/console ezpublish:configure --env=prod <group> <admin-siteaccess>

assets

To be able to run eZ Publish 5 correctly, assets need to be exposed in the public 'web' folder.

The following commands will first symlink eZ Publish 5 assets in "Bundles" and the second will symlink assets (design files like images, scripts and css, and files in var folder)  from eZ Publish Legacy:

php ezpublish/console assets:install --symlink web
php ezpublish/console ezpublish:legacy:assets_install --symlink web
php ezpublish/console assetic:dump --env=prod web

Note: In both cases "web" is the default folder and can be skipped from the command. Further information about alternative options is available with -h just like it is with "php ezpublish/console -h"

Step 7: Fix images outside the var dir

This step is optional if you didn't changed the default location of eZ Publish's "var" dir.
If you intend to use a different location for the "var" dir paths to images may need to be fixed.
For that, please be sure to copy or move all the content from your initial var dir location, into your new var dir location.
Then, run the following script to fix the file locations:

cd /<ezp5-root>/ezpublish_legacy/
php update/common/scripts/5.1/fiximagesoutsidevardir.php

IMPORTANT: This script only fixes the path to images. Binary files can be fixed on non clustered environnements (FS) by moving the storage/original folder to the new location. This workaround does not apply to DB/DFS setups.

Step 8: Clear 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 new eZ Publish directory.
2. Run the script using the following shell command:

cd /<ezp5-root>/ezpublish_legacy/
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.

Note: 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 sub-directories 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.

Step 9: Update rewrite rules

There are two ways eZ Publish 5 can be installed, either the full install with both the new Symfony stack and the legacy stack, or legacy only. In latter case you only need to point your '4.7 like' rewrite rules to /<ezp5-root>/ezpublish_legacy/ and that's it. Otherwise, update your virtual host according to the eZ Publish 5.1 rewrite rules on confluence and point your host configuration to /<ezp5-root>/web/.

Step 10: Upgrade Extensions (site package)

Next, depending on if you originally installed eZ Flow, eZ Webin or eZ Demo site, follow the steps mentioned in the eZ Webin, eZ Flow or eZ Demo upgrade documentation.

Known issue

For a list of known issues related to the 5.1 version, please be sure to check the related page on confluence.