This section describes how to upgrade your existing eZ Publish 5.2 i= nstallation to version 5.3. 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.
PHP 5.3.3 and higher is needed. Further information regarding system req= uirements can be found on Requirements Doc= umentation Page.
The easiest way to upgrade the distribution files is to unpack eZ Publis= h 5.3 to a separate directory and then copy the directories that contain si= te-specific files from the existing 5.2 installation into "/<ezp5-ro= ot>/". Make sure you copy the following directories:
ezpublish_legacy/design/<your designs> (do NOT inclu=
de built-in designs: admin, base, standard or admin2)ezpublish_legacy/var/<your_var_dir>/storageezpublish_legacy/var/storage/packagesezpublish_legacy/settings/siteaccess/<your_siteaccesses>ezpublish_legacy/settings/override/*ezpublish_legacy/extension/* (not including the built-in /=
standalone ones: ezflow, ezjscore, ezoe, ezodf, ezie, ezmultiupload, ezmbp=
aex, ez_network, ezprestapiprovider, ezscriptmonitor, ezsi, ezfind)config.php & config.cluster.php, if appli=
cableezpublish/config/*NB: Since writable directories and files have = been replaced / copied, their permissions might have changed. You may have = to reconfigure webserver user permissions on specific folders as explained = in the file permissions chapter= of the installation process.
If you are using custom extensions, the sub-directories inside the "exte= nsion" directory will also have to be copied from the existing 5.2 ins= tallation into "/<ezp5-root>/ezpublish_legacy/extension/". H= owever, make sure that you do not overwrite any extensions that are include= d in eZ Publish distribution, which currently are (Note: As of eZ Publish 5.2, these extensions have the same version n= umber as eZ Publish):
Note that upgrading the distribution files will overwrite the autoload a= rrays for extensions. You will need to re-generate the autoload arrays for = active extensions later.
Important: If you plan to upgrade your eZ Webs= ite Interface, eZ Flow or eZ Demo site package as well, then additiona= l extensions will be updated and the step for re-generate the aut= oload 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).<= /em>
This step assumes use of the built in database drivers, mysql (inc= l mariadb) and PostgreSQL, for other databases supported via extension plea= se use scripts and documentation provided by extension.
Import to your database the changes provided in
/<ezp5-root>/ezpublish_l=
egacy/update/database/<mysql|postgresql>/5.3/dbupdate-5.2.0-to-5.3.0.=
sql
ezpublish.system.<siteAccessName>.database has been r=
emoved for defining database settings. You now need to:
doctrine:
dbal:
connections:
my_connection:
driver: pdo_mysql
host: localhost
port: 3306
dbname: my_database
user: my_user
password: my_password
charset: UTF8=20
doctrine:
dbal:
connections:
my_connection:
driver: pdo_pgsql
host: localhost
port: 5432
dbname: my_database
user: my_user
password: my_password
charset: UTF8=20
Pro Tip
parameters.yml/
parameters.yml.dist and refer them here.
parameters: database_driver: pdo_mysql database_host: localhost database_port: 3306 database_name: ezdemo database_user: my_user database_password: my_password database_charset: UTF8=20
doctrine:
dbal:
connections:
my_connection:
driver: %database_driver%
host: %database_host%
port: %database_port%
dbname: %database_name%
user: %database_user%
password: %database_password%
charset: %database_charset%=20
ezpublish:
repositories:
main: { engine: legacy, connection: my_connection }=20
ezpublish:
system:
my_siteaccess_group:
repository: main=20
Remove the old connection information
Note : to benefit from the new configuration, don't forget to remove the= old configuration
ezpublish:
system:
my_siteaccess_group:
database:
type: mysql
user: my_user
password: my_password
server: localhost
database_name: ezdemo
=20
Since default configuration files have been overwritten during step one,=
the few additions to those files that were made in 5.2 need to be applied =
manually to the configuration files.
All of those changes are
For most of them, at least one, if not all hierarchy elements (monolog, = handler, framework, router...) will already be there. All you have to do is= add the missing bits in the existing configuration blocks= .
In ezpublish/config/config.yml, you need = to add a few default values for the framework
ezpublish.system.<siteAccessName>.session_name has be=
en deprecated for defining session name. You now need to use ezpublis=
h.system.<siteAccessName>.session.name.
Before:
ezpublish:
system:
my_siteaccess:
session_name: SomeSessionName=20
After:
ezpublish:
system:
my_siteaccess:
session:
name: SomeSessionName=20
In rout=
ing.yml, add new login routes and the =
_ezpublishRestOptionsRoutes route loader:
_ezpublishRestOptionsRoutes:
resource: "@EzPublishRestBundle/Resources/config/routing.yml"
prefix: %ezpublish_rest.path_prefix%
type: rest_options
login:
path: /login
defaults: { _controller: ezpublish.security.controller:loginAction }
login_check:
path: /login_check
logout:
path: /logout=20
In ezpubl=
ish/config/security.yml, under ezpublish_fron=
t firewall, update to fit the following (be sure to remove <=
code>ezpublish: true):
security:
firewalls:
ezpublish_front:
pattern: ^/
anonymous: ~
form_login:
require_previous_session: false
logout: ~=20
If you have added anything to pa=
rameters.yml, we suggest that you add your custom settings to =
parameters.yml.dist, so that the composer post-update script handles=
those, and generates their values correctly.
In your templates, change your links p=
ointing to /user/login and /user/logout to approp=
riate login / login_check / logou=
t routes:
<a href=3D"{{ path( 'ez_legacy', {'module_uri': '/user/login'} )=
}}">Login</a>
<form action=3D"{{ path( 'ez_legacy', {'module_uri': '/user/login'} ) }}=
" method=3D"post">
<a href=3D"{{ path( 'ez_legacy', {'module_uri': '/user/logout'} ) }}">=
;Logout</a>=20
<a href=3D"{{ path( 'login' ) }}">Login</a>
<form action=3D"{{ path( 'login_check' ) }}" method=3D"post">
<a href=3D"{{ path( 'logout' ) }}">Logout</a>=20
It is not possible to just copy your old EzPublishKernel.php file over from the previous installation, since quite a few changes were =
made to this file in this release. We suggest that you simply reflect in th=
e new kernel file any changes you made in the previous version.
If you had modified composer.json to add your own requireme=
nts, you must re-apply those changes to the new version, and run
Anonymous state of a user is not checked through presence of is_lo=
gged_in cookie any more. Therefore, when using Varnish, you must cha=
nge the following in your VCL file:
# ez_user_hash sub-routine
if (req.http.Cookie !~ "is_logged_in=3D" ) {
# User don't have "is_logged_in" cookie =3D> Set a hardcoded anonymo=
us hash
set req.http.X-User-Hash =3D "38015b703d82206ebc01d17a39c727e5";
}=20
# ez_user_hash sub-routine
if (req.http.Cookie !~ "eZSESSID" ) {
# User don't have session cookie =3D> Set a hardcoded anonymous hash
set req.http.X-User-Hash =3D "38015b703d82206ebc01d17a39c727e5";
}=20
To regenerate the autoload array, execute the following script from the = root of your eZ Publish Legacy directory:
cd ezpublish_legacy php bin/php/ezpgenerateautoloads.php --extension=20
Assets from the various bundles need to be made available for the webser= ver through the web/ document root.
The following commands will first symlink eZ Publish 5 assets in "Bundle= s" and the second will symlink assets (design files like images, scripts an= d css, and files in var folder) from eZ Publish Legacy:
php ezpublish/console assets:install --symlink php ezpublish/console ezpublish:legacy:assets_install --symlink php ezpublish/console assetic:dump --env=3Dprod=20
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:
Navigat=
e into the new eZ Publish directory.Run the script using the following shel=
l command:cd /<ezp5-root>/ezpublish_legacy/php bin/php/ezcache.php --=
clear-all --purgePurging ensures that the caches are physically removed. Wh=
en the "--purge" parameter is not specified, the caches will be expired but=
not removed.
Note: Sometimes the script is unable to clear all cache fi=
les because of restrictive file/directory permission settings. Make sure th=
at all cache files have been cleared by inspecting the contents of the vari=
ous cache sub-directories within the "var" directory (typically the "var/ca=
che/" and "var/<name_of_siteaccess>/cache/" directories). If there ar=
e any cache files left, you need to remove them manually.
Next, depending on if you originally installed eZ Flow, eZ Webin or eZ D= emo site, follow the steps mentioned in the eZ Webin, eZ Flow or eZ Demo upgrade documentatio= n.
Please have in mind that, after the upgrade to a major version of eZ Pub= lish, you will need to perform regular updates with composer.
Before any minor update with composer, please execute all require steps = described in the 5.3.x U= pdate Instructions.