Keeping your system up-to-date is important to make sure it is running optimally and securely. The update mechanism in eZ software is using standard PHP packaging system called Composer.
This makes it easy to adapt package installs and updates to your workflow, allowing you to test new/updated packages in a development environment, place the changes in your version control system (git, Subversion, Mercurial, etc.), pull in those changes to a staging environment and, when approved, put them in production.
Composer is a command-line tool, so the main way to install it is via command line from inside the root directory of the (eZ) software:
Composer download in current folder:
php -r "readfile('https://getcomposer.org/installer');" | php
By doing it this way you will need to execute further Composer commands using
php composer.phar. If you prefer to install Composer globally on your machine instead of inside each and every project that uses it, then follow these instructions in online Composer documentation.
Prerequisite to using Composer with eZ Enterprise software¶
Setting up Authentication tokens for access to commercial updates¶
Out of the box Composer uses a packaging repository called packagist.org to find all open-source packages and their updates. Additional commercial packages are available for eZ Enterprise subscribers at updates.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 Support agreement details" screen:
Click "Create token" (This requires the "Portal administrator" access level.)
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 good 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 – your Installation key found above on the "Maintenance and Support agreement details" page in the service portal
- as Password – the token password you retrieved in step 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 disabled, you can create an
auth.json file manually in one of the following ways:
- Option A: Store your credentials in the project directory:
composer config http-basic.updates.ez.no <installation-key> <token-password>
- Option B: If you'd rather want to install it globally in COMPOSER_HOME directory for machine-wide use:
composer config --global http-basic.updates.ez.no <installation-key> <token-password>
Update workflow Using Composer¶
This section describes the best practice for using Composer, you should treat updates like other code/configuration/* changes on your 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 illustration here is how you update your project locally:
php -d memory_limit=-1 composer.phar update --no-dev --prefer-dist
This will load in all updated packages, from eZ as well as third-party libraries, 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 know 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 the classes/interfaces in it have changed. This can be done in the following way:
Optional prod class cache clearing
rm -f var/cache/prod/*.php
When the update has completed and local install is verified to work, make sure to version changes done to the
composer.lock file (if you use a version control system like git). This file 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).
In large development teams make sure people don't blindly update and install third party components. This might easily lead to version conflicts on
composer.lock and can be tiring to fix up if happening frequently. A workflow involving Composer install and unit test execution on proposed changes can help avoid most of this, like the Pull Request workflow available via Github/Bitbucket.
2. Installing versioned updates on other development machines and/or staging -> production¶
Installing eZ software packages via Composer is nothing different then installing vanilla packages via Composer, and for illustration here is how you install versioned updates:
composer install (package installation)
php -d memory_limit=-1 composer.phar install --no-dev --prefer-dist
This command will tell Composer to install packages in exactly the same version as defined in
composer.lock. If you don't keep track of
composer.lock, it will instead just install always the latest version of a package and won't allow you to stage updates before moving towards production.
General notes on use of Composer¶
Installing additional packages via Composer¶
composer install (package installation)
php -d memory_limit=-1 composer.phar require --prefer-dist ezcommunity/ez-price-bundle:~1.0.0@beta
Dumping autoload for better performance¶
For PHP 5.6 and up you'll get a notable performance improvement by making Composer dump optimized autoload array, this can be done on Composer install and update, but also using:
php -d memory_limit=-1 composer.phar dump-autoload --optimize
Cloning failed using an ssh key¶
When dealing with updates.ez.no packages, you might get this if you somehow tell Composer to download dev packages, or tell it to download from source. Currently our updates.ez.no service only support distribution packages in alpha stability or higher, so make sure to check what stability and avoid use of
--prefer-source (this is the reason examples above are using
Conflict with roave/security-advisories¶
When you use Composer update or require, a package may conflict with
1 2 3 4
Your requirements could not be resolved to an installable set of packages. Problem 1 - ezsystems/ezpublish-legacy v5.4.10 conflicts with roave/security-advisories[dev-master]. (...)
This means there is a known security bug in the specific version of the package, ezsystems/ezpublish-legacy. In most cases this means that a fix is available in a newer version. If you increase your requirement to that version, the conflict is resolved.
In the rare case that there is no fixed version, you can revert your requirement to an older version which does not have the bug. If you have to use the version with the bug (not recommended) you can
composer remove roave/security-advisories. In that case, please require it again when the bug is fixed and the package is updated:
composer require roave/security-advisories:dev-master
Best practice for Bundles¶
Best practice for Bundles is described in Symfony documentation under Best Practices for Reusable Bundles, with eZ bundles there is some notable exceptions:
- You may write your documentation using markdown (.md) if you prefer, however .rst is recommended if you plan to use writethedocs.org, as 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 name which is more relevant when trying to find a given package later.
- For defining
type, the following are at the moment known valid values:
ezplatform-bundle| Symfony bundles that uses eZ Platform features
symfony-bundle| Standard symfony bundles as described in Symfony doc.
Regardless of the type you set, always remember to specify package dependencies in Composer requirements so the dependencies are clear. For example if you reply on
ezsystems/landing-page-fieldtype-bundle make sure to add that with the major versions you support of it.
Composer for Frontend Developers¶
If you are a web designer or working on the CSS on your website, this section contains all you need to know about Composer.
You may experience some latency in dependency resolution: everything is going normally.
If you are interested by the process, do your Composer commands with the
--verbose option activated.
Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
php -d memory_limit=-1 composer.phar <command> --verbose (-v|vv|vvv)
install command reads the
composer.lock file from the current directory, processes it, and downloads and installs all the libraries and dependencies outlined in that file. If the file does not exist it will look for
composer.json and do the same.
php -d memory_limit=-1 composer.phar install --dry-run --prefer-dist
In this example the
dry-run option is mentioned to prevent you from doing anything critical. (This option outputs the operations but will not execute anything and implicitly enables the verbose mode).
Documentation with complete usage:¶
php -d memory_limit=-1 composer.phar install [--prefer-source] [--prefer-dist] [--dry-run] [--dev] [--no-dev] [--no-plugins] [--no-custom-installers] [--no-scripts] [--no-progress] [-v|vv|vvv|--verbose] [-o|--optimize-autoloader] [packages1] ... [packagesN]
update command reads the composer.json file from the current directory, processes it, and updates, removes or installs all the dependencies.
To limit the update operation to a few packages, you can list the package(s) you want to update as such:
php -d memory_limit=-1 composer.phar update vendor/package1 foo/mypackage
You may also use an asterisk (*) pattern to limit the update operation to package(s) from a specific vendor:
php -d memory_limit=-1 composer.phar update vendor/package1 foo/*
Composer for System Administrators¶
Composer is an opensource PHP packaging system to manage dependencies.
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.
The following examples use a
composer install global command, as alternative use
php composer.phar <command>.
You should use the command-line according to your installation.
||No rights needed. No configuration needed (out of the box).|
||Every user on the server can access Composer CLI. You have your Composer outside your web root directory.|
curl -sS https://getcomposer.org/installer | php
or (according to your user rights on your system)
php -r "readfile('https://getcomposer.org/installer');" | php
curl -sS https://getcomposer.org/installer | php mv composer.phar /usr/local/bin/composer
See the Composer documentation for further information
Composer requires PHP 5.3.2+ to run.
Useful Composer commands for System Administrators¶
as usual with CLI, you can type:
$> php composer.phar help [--xml] [--format="..."] [--raw] [command_name]
to get help for the command.
On this page you will find some useful commands and an extract of the Composer Documentation. The interesting options part is an extract of available options
show command displays detailed information about a package, or lists all available packages.
php composer.phar show [-i|--installed] [-p|--platform] [-a|--available] [-s|--self] [-N|--name-only] [-P|--path] [package] [version]
require command adds required packages to your
composer.json and installs them. If you do not want to install the new dependencies immediately, you can call it with
php composer.phar require [--dev] [--prefer-source] [--prefer-dist] [--no-progress] [--no-update] [--update-no-dev] [--update-with-dependencies] [packages1] ... [packagesN]
|--prefer-source||Forces installation from package sources when possible, including VCS information|
|--prefer-dist||Forces installation from package dist even for dev versions|
|--no-progress||Removes output download progress|
|--no-update||Disables the automatic update of the dependencies|
|--update-with-dependencies||Allows inherited dependencies to be updated with explicit dependencies|
search command searches for packages by its name.
$> php composer.phar search symfony composer
can return to you a list like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
symfony/assetic-bundle Integrates Assetic into Symfony2 symfony/monolog-bundle Symfony MonologBundle ezsystems/ngsymfonytools-bundle Bundle of the legacy netgen/ngsymfonytools extension symfony-cmf/routing Extends the Symfony2 routing component for dynamic routes and chaining several routers doctrine/doctrine-bundle Symfony DoctrineBundle nelmio/cors-bundle Adds CORS (Cross-Origin Resource Sharing) headers support in your Symfony2 application tedivm/stash-bundle Incorporates the Stash caching library into Symfony. egulias/listeners-debug-command-bundle Symfony 2 console command to debug listeners hautelook/templated-uri-router Symfony2 RFC-6570 compatible router and URL Generator hautelook/templated-uri-bundle Symfony2 Bundle that provides a RFC-6570 compatible router and URL Generator. symfony/swiftmailer-bundle Symfony SwiftmailerBundle white-october/pagerfanta-bundle Bundle to use Pagerfanta with Symfony2 symfony/icu Contains an excerpt of the ICU data and classes to load it. symfony/symfony The Symfony PHP framework sensio/distribution-bundle The base bundle for the Symfony Distributions symfony/symfony The Symfony PHP framework symfony/console Symfony Console Component symfony/filesystem Symfony Filesystem Component symfony/finder Symfony Finder Component symfony/process Symfony Process Component symfony/yaml Symfony Yaml Component symfony/translation Symfony Translation Component symfony/debug Symfony Debug Component symfony/routing Symfony Routing Component symfony/icu Contains an excerpt of the ICU data to be used with symfony/intl. symfony/config Symfony Config Component symfony/validator Symfony Validator Component symfony/stopwatch Symfony Stopwatch Component symfony-cmf/symfony-cmf Symfony Content Management Framework
validate command validates a given composer.json.
$> php composer.phar validate [--no-check-all] [file]
|--no-check-all||Do not perform complete validation|
|--profile||Display timing and memory usage info|
|--working-dir (-d)||If specified, use the given directory as a working directory|
Note that you can add some scripts to the Composer dependencies installation.
The available events are :
See the Composer documentation about scripts for more information