This section describes how to upgrade your existing eZ Publish 5.3 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.3 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 & ezpub=
lish_legacy/config.cluster.php, if applicableezpublish/config/*.ymlNB: 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.3 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_legacy/update/database/<mysql|post=
gresql>/5.4/dbupdate-5.3.0-to-5.4.0.sql
If the installation is using the DFS cluster, import the cluster databas=
e changes provided in/<ezp5-root>/ezpublish_legacy/update/d=
atabase/mysql/5.4/dbupdate-cluster-5.3.0-to-5.4.0.sql
Since default configuration files have been overwritten during step one,=
the few additions to those files that were made in 5.3 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= .
trusted_hosts has been changed and session.handler_id&= nbsp;is added to the framework block making Symfony 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 completely.
Add the liip imagine routes to the file:
_liip_imagine: resource: "@LiipImagineBundle/Resources/config/routing.xml"=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.
ezpublish_legacy.default.view_default_layout can be removed fro= m 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
In all ezpublish.yml files (prod, dev, etc), replace the "handle= rs" key in stash.caches.* with "drivers"= .
stash:
caches:
default:
drivers:=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 update the ne=
w kernel file with any changes you made in the previous version.
New bundles in this version are EzPublishIOBundle, FOSHttpCacheBundle, LiipImagineBundle, WhiteOctoberBreadcrumbsBundle, KnpMenuBundle, OneupFlysystemBundle and
If you had modified composer.json to add your own requireme=
nts, you must re-apply those changes to the new version.
Note: Besides requirements changes there are also changes to other p= arts of composer.json, including improvements also found in 5.3.3 and 5.3.4.
The recommended varnish (3 and 4) VCL configuration can now be found in =
the doc/varnish folder. See also the Using Varnish page.
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 <=
code>doc folder, for both apache2 (doc/apache2) an=
d nginx (doc/nginx). Both are built to be easy to underst=
and and use, but aren't meant as drop-in replacements for your existing con=
figuration.
One notable change is that SetEnvIf is now used to dyn=
amically change rewrite rules depending on the Symfony environment. It is c=
urrently used for the assetic production rewrite rules.
Read more on the Web servers pa= ge.
This is reflected in the apache2 and nginx configuration files that are =
shipped in the doc folder. The main change from legacy is that requests for=
images can now be rewritten to web/index.php instea=
d of ezpublish_legacy/index_cluster.php.
Run composer update --no-dev --prefer-dist to get the lates=
t 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/ezcac=
he.php --clear-all --purge. Purging ensures that the caches are phys=
ically removed. When the "--purge" parameter is not specified, the caches w=
ill be expired but not removed.
Note: Sometimes the script is unable to =
clear all cache files because of restrictive file/directory permission sett=
ings. Make sure that all cache files have been cleared by inspecting the co=
ntents of the various cache sub-directories within the "var" directory (typ=
ically the "var/cache/" and "var/<name_of_siteaccess>/cache/" directo=
ries). If there are any cache files left, you need to remove them manually.=
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.