Upgrading from 4.7 to 5.0

This section describes how to upgrade your existing eZ Publish 4.7 installation to version 5.0. 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.0 consists of the following steps:

Upgrade the distribution files
Upgrade custom extensions
Upgrade the database
Run scripts
Regenerate the autoload array for extensions
Generate eZ Publish 5 yml configuration & symlink assets
Clear the caches
Update rewrite rules
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 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}

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):

Extension name	Folder name	Note
eZ Flow	ezflow
eZ JSCore	ezjscore
eZ Online Editor	ezoe
eZ OpenOffice Document Format	ezodf
eZ Image Editor	ezie
eZ Multiupload	ezmultiupload
eZ MB Password Expiry	ezmbpaex
eZ Network	ez_network
eZ REST API Provider	ezprestapiprovider
eZ Script Monitor	ezscriptmonitor
eZ SI	ezsi
eZ Find	ezfind	Optional install

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 script 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

You can run this 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

The autoload system has undergone some changes also. For instance: the autoload array for extensions is now placed in var/autoload of your eZ Publish installation (along with the class changes in extensions itself).

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

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

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: 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:

Navigate into the new eZ Publish directory.
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 8: 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 rewrite rules to resemble this and point it to /<ezp5-root>/web/.

Step 9: 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

Lazy sessions not supported

As Symfony always forces the creation of sessions, and regarding the way eZ Publish has this feature implemented, lazy sessions is currently not supported on eZ Publish 5.x.

Please note that the "ForceStart" setting still exists in eZ Publish 5 legacy, but it will not take any effect, since the creation of a session is always forced by Symfony.
Also please be aware that using this setting with Varnish or other similar caching systems may generate additional cache issues.