Keeping your system up-to-date is important to make sure it is running o= ptimally and securely. The update mechanism in eZ software is using th= e de facto standard PHP packa= ging system called Composer.
This makes it easy to adapt package installs and updates to your workflo= w, allowing you to test new/updated packages in a development environment, = place the changes in your version control system (git, Subversion, Mercuria= l, etc.), pull in those changes to a staging environment and, when approved= , put them in production.
Composer is an opensource PHP packaging system to manage dependen= cies.
This makes it easy to adapt package installs and updates to your workflo= w, 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.
Installing Composer
Composer is a command-line tool, so the main way to install it is via co= mmand line from inside the root directory of the (eZ) software:
php -r "readfile('https://getcomposer.org/installer');" | php=20
By doing it this way you will need to execute further Composer commands =
using php composer.phar. If you'd rather prefer to install Com=
poser globally on your machine instead of inside each and every project tha=
t uses it, then follow these instructions in onl=
ine Composer documentation.
Prerequisite to using composer with eZ Enterprise software
This section describes features available only in eZ Enterprise.=
=20Setting up Authentication tokens for access to commercial= updates
Out of the box Composer uses a packaging repository called packagist.or= g to find all open-source packages and their updates. Additional commer= cial packages are available for eZ Enterprise subscribers at up= dates.ez.no/bul/ (which is password-protected, you will need to set= up authentication tokens as described below to get access).
To get access to these updates log in to your service portal on support= .ez.no and look for the following on the "Maintenance and Supp= ort agreement details" screen:
- Click "Create token" (This requires the "Portal administrator" access l= evel.)
- Fill in a label describing the use of the token. This will allow you to=
revoke access later.
- Example, if you need to provide access to updates to a third party, a g= ood example would be "53-upgrade-project-by-partner-x"
- Copy the password, you will not get access to it again= !
After this, when running Composer to get updates as described below, you= will be asked for a Username and Password. Use:
- as Username =E2=80=93 your Installation key found above on the
- as Password =E2=80=93 the token password you retrieved in st= ep 3.
Support agreement expiry
If your Support agreement expires, your authentication token(s) will no = longer work. They will become active again if the agreement is renewed, but= this process may take up to 24 hours. (If the agreement is renewed before = the expiry date, there will be no disruption of service.)
Optional: Save authentication information in auth.= json to avoid repeatedly typing it
Composer will ask to do this for you on updates, however if it is disabl=
ed, you can create an auth.json file manually in one of t=
he following ways:
Option A: Store your credentials in the project directory:=
composer config http-basic.updates.ez.no <installation-key> = <token-password>=20
Option B: If you'd rather want to install it globally in <= a href=3D"https://getcomposer.org/doc/03-cli.md#composer-home" class=3D"ext= ernal-link" rel=3D"nofollow">COMPOSER_HOME directory for machine-w= ide use:
composer config --global http-basic.updates.ez.no <installation= -key> <token-password>=20
Update workflow U= sing Composer
This section describes the best practice for using Composer, essentially= it suggests treating updates like other code/configuration/* changes on yo= ur project, tackling them on a development machine before staging them for = rollout on staging/production.
1. Running composer update and version changes in development
Updating eZ software via Composer is nothing different then updating other projects via Composer, but for illustrat= ion here is how you update your project locally:
php -d memory_limit=3D-1 composer.phar update --no-dev --prefer-di= st=20
This will load in all updated packages, from eZ as well as third-party l= ibraries, both used by eZ and other you may have added. When updating like = this it is recommended to take note of what was updated so you have an idea= of what you should test before putting the updates into production.
At this stage you might need to manually clear Symfony's prod environment class cache (cached interfaces and lazy services) in case th=
e classes/interfaces in it have changed. This can be done in the following =
way:
rm -f app/cache/prod/*.php=20
When the update has completed and local install is verified to work, mak=
e sure to version changes done to the composer.lock file (if y=
ou use a version control system like git). This file contains
In large development teams make sure people don't blindly update and ins=
tall third party components. This might easily lead to version conflicts on=
composer.lock and can be tiring to fix up if happening freque=
ntly. A workflow involving composer install and unit test execution on prop=
osed changes can help avoid most of this, like the Pull Request workflow av=
ailable via Github/Bitbucket.
production">2. Installing versioned updates on other deve= lopment machines and/or staging -> production
Installing eZ software packages via Composer is nothing different t= hen installing vanilla packages via Composer, and for illustration here is how you install versioned updates:
php -d memory_limit=3D-1 composer.phar install --no-dev --prefer-di= st=20
composer.lock comes in, as this command will tell Composer to =
install packages in exactly the same version as defined in this file. If yo=
u don't keep track of=20
composer.lock, it will instead just install always the latest =
version of a package and won't allow you to stage updates before moving tow=
ards production.
General notes on use o= f Composer
Installing= additional packages via Composer
Requiring eZ software packages via Composer is also done in sa= me way as requiring vanilla packages via Compo= ser, and for illustration here is how you install the community-develop= ed EzPriceBundle:
php -d memory_limit=3D-1 composer.phar require --prefer-dist ezcomm= unity/ez-price-bundle:~1.0.0@beta=20
Dumping autolo= ad for better performance
For PHP 5.6 and up you'll get a notable performance improvement by makin= g composer dump optimized autoload array, this can be done on composer inst= all and update, but also using:
php -d memory_limit=3D-1 composer.phar dump-autoload --optimize
Best practice for Bundles
Best practice for Bundles is described in Symfony documentation under&nb= sp;Best Practices for Reusabl= e Bundles, with eZ bundles there is some notable exceptions:
Documentation
- You may write your documentation using markdown (.md) if you prefer, ho= wever .rst is recommended if you plan to use writethedocs.org, a= s heavily used by many open source projects.
Git repository naming
- You may omit vendor name in repository naming, assuming vendor name is = reflected in organization / user account it is attached to.
- You may also choose to follow composer package naming on repository nam= e which is more relevant when trying to find a given package later.
Composer Metadata
- For defining
"type", the = following are at the moment known valid values:ezplatform-bundleezstudio-bundle | <= span style=3D"color: rgb(128,128,128);">Symfony bundles that uses eZ Platfo= rm Enterprise Edition featuressymfony-bundle| Standard symfony bundles as descr= ibed in Symfony doc.
- For eZ Publish (legacy) and eZ Publish Platform there where also:
ezpublish-legacy-extension | For standalone 4.x (l= egacy) extensions, to be used with e= zpublish-legacy-installerezpublish-bundle | For eZ Publish Platform 5.x bundles, = may optionally be a "lega= cy bundle".