This section describes how to upgrade your existing eZ Publish 5.2 i= nstallation to version 5.4. 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.4.4 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.4 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)ezpublish_legacy/config.php & ezpublish_legacy/config.cluster.php ezpublish/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 installa= tion into "/<ezp5-root>/ezpublish_legacy/extension/". Howeve= r, make sure that you do not overwrite any extensions that are included in = eZ Publish distribution, which currently are (Note: In eZ Publish Platform 5.4, extensions have version number 5.3 with= exception of ezdemo, ezoe, ezformtoken, ezjscore and ezfind):
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
and
/<ezp5-root>/ezpublish_leg= acy/update/database/<mysql|postgresql>/5.4/dbupdate-5.3.0-to-5.4.0.sq= l
If the installation is using the DFS cluster, import the cluster d=
atabase changes provided in/<ezp5-root>/ezpublish_le=
gacy/update/database/mysql/5.4/dbupdate-cluster-5.3.0-to-5.4.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
trusted_hosts has been changed and session.handle= r_id is added to the framework block making Sy= mfony pick what has been configured in PHP instead.
framework:
trusted_hosts: ~
session:
handler_id: ~=20
Additionally configuration for swift_mailer has been = added:
swiftmailer:
transport: "%mailer_transport%"
host: "%mailer_host%"
username: "%mailer_user%"
password: "%mailer_password%"
spool: { type: memory }=20
In framework, set router.strict_requirements to true.=
framework:
router:
resource: "%kernel.root_dir%/config/routing_dev.yml"
strict_requirements: true=20
Remove framework.router.strict_requirements.
Add new login routes, _ezpublishRestOptionsR=
outer route loader, and and _liip_imagine:
_ezpublishRestOptionsRoutes:
resource: "@EzPublishRestBundle/Resources/config/routing.yml"
prefix: %ezpublish_rest.path_prefix%
type: rest_options
_liip_imagine:
resource: "@LiipImagineBundle/Resources/config/routing.xml"
login:
path: /login
defaults: { _controller: ezpublish.security.controller:loginAction }
login_check:
path: /login_check
logout:
path: /logout=20
Under ezpublish_front fir=
ewall, update to fit the following (be sure to remove ezpubli=
sh: true):
security:
firewalls:
ezpublish_front:
pattern: ^/
anonymous: ~
form_login:
require_previous_session: false
logout: ~=20
If you have added anything to parame=
ters.yml, we suggest that you add your custom settings to
ezpublish_legacy.default.view_default_layout can be remove= d from this file, and the following added:
parameters:
mailer_transport: smtp
mailer_host: 127.0.0.1
mailer_user: ~
mailer_password: ~=20
composer will ask for your own values when you run&nb= sp;composer update.
In all ezpublish.yml files (prod, dev, etc), replace the "handle= rs" key in stash.caches.* with "drivers= ".
stash:
caches:
default:
drivers:=20
ezpublish.system.<siteAccessName>.session_name h=
as been deprecated for defining session name. You now need to use
Before:
ezpublish:
system:
my_siteaccess:
session_name: SomeSessionName=20
After:
ezpublish:
system:
my_siteaccess:
session:
name: SomeSessionName=20
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.
The recommended varnish (3 and 4) VCL configuration can now be fou=
nd in the doc/varnish folder. See also =
the Using Varnish
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
If your legacy installation uses DFS clustering, you need to create the new stack config= uration for it.
The officially recommended virtual configuration is now shipped in the&n=
bsp;doc folder, for both apache2 (doc/apache2) and nginx (doc/nginx). Both are built to be easy to un=
derstand and use, but aren't meant as drop-in replacements for your existin=
g configuration.
One notable change is that SetEnvIf is now used t=
o dynamically change rewrite rules depending on the Symfony environment. It=
is currently used for the assetic production rewrite rules.
Read more on the Web servers page.
Run composer update --no-dev --prefer-dist to get=
the latest eZ Publish dependencies.
At the end of the process, you will be asked for values for the paramete=
rs previously added to parameters.yml.dist.
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.4.x Update Instructions.