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.
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:
php 5.3.3 and higher is needed. Further information regarding system requirements can be found on Requirements Documentation Page.
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:
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:
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}
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}
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 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
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).
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.
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.
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
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>
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"
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.
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:
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.
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/.
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.
For a list of known issues related to the 5.1 version, please be sure to check the related page on confluence.
Powered by eZ Publish™ CMS Open Source Web Content Management. Copyright © 1999-2013 eZ Systems AS (except where otherwise noted). All rights reserved.