eZ Publish Platform 5.3 and higher
This page only applies to eZ Publish Platform 5.3 and higher, for earlier versions of the Enterprise version of eZ Publish consult Service Portal user guide available for download at support.ez.no. This page is also generic about using composer, for instructions specific to a release, see release notes.
Keeping your system up-to-date is important, to make sure your it is running optimally and securely. The update mechanism in eZ Publish Platform is using the de facto standard PHP packaging system called Composer for this. This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, put the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes on a staging environment and, when approved, put it in production.
Prerequisite to using composer
Setting up Authentication tokens for access to commercial updates
Out of the box composer uses a packaging system called packagist.org for all open source packages and their updates, in eZ Publish Platform additional commercial packages are available at updates.ez.no/bul/ (password protected, you'll need to setup authentication tokens as described below to get access).
To get access to these updates go to your service portal on support.ez.no, your project will need to be configured for eZ Publish Platform 5.3 or higher and you will have access to the following on the "Maintenance and Support agreement details" screen:
- Click "Create token"
- Fill in a label describing the use of the token
- Example, if you need to provide access to updates to a third party a good to example would be "53-upgrade-project-by-partner-x", this will allow you to revoke access later.
- Copy the password, you will not get access to this again!
For login to get updates, use your Installation key found higher up on the same page, and the password you retrieved and saved in step 3.
Optional: Save authentication token in auth.json to avoid repeatedly typing
To avoid having to always fill your credentials, bundled with eZ Publish Platform is a Composer extension which makes it possible to put this informations in a
Short: Add an
auth.json file at your project root, aside
composer.json, or in your COMPOSER_HOME directory for machine wide use, the file looks like the following:
This step is only needed once per machine (per project by default, but globally on machine also possible, for alternatives see: https://getcomposer.org/download/).
Composer is a command line tool, so the main way to install it is via command-line, example with only requirement on PHP being installed:
# Running composer update and version changes
Updating eZ Publish Platform via composer is nothing different then updating other projects via composer, but for illustration here is how you update your project locally:
When this has completed, make sure to version (assuming you use a version control system) changes done to
composer.lock file. This is the file that contains all details of which versions are currently used and makes sure the same version is used among all developers, staging and eventually production when current changes are approved for production (assuming you have a workflow for this).
# Installing versioned updates on other development machines and/or staging
Installing eZ Publish Platform packages via Composer is nothing different then installing vanilla packages via Composer, and for illustration here is how you install versioned updates:
# Installing eZ packages via composer
Also requiring eZ Publish Platform packages via composer is nothing different then requiring vanilla packages via Composer, and for illustration here is how you install a eZ package:
# Notes on using Composer with Legacy
(eZ Publish) Legacy by design places all important customizable folders within it's own structure. This is not ideal with Composer, as installation and updates might cause them to become as provided by packages again.
To make sure you are safe from this, and to allow you to version these custom folders independently, it is recommended that you use symlinks and keep your custom settings, extensions and design outside of the ezpublish_legacy folder. To not have to manually deal with these symlinks it is recommended to use Composer
post-update-command script commands to make this automated.
All extensions not provided via composer is affected by this as well, currently the following extensions from eZ is not provided via composer and needs to be setup like proposed in this section: eznetwork, ezcontentstaging, ezrecommendation and ezma.
Below is a illustration on how this can be setup, see Composer documentation for further info.
Note: This functionality is desirable to have out of the box in the future, so community contributions on this topic is welcome to find a good standard convention and script to handle it.