Composer

We use Composer to manage dependencies and upgrades in Magento Commerce (Cloud) and provide context about the included packages, what the packages do, and how they fit together. We highly recommend experience with Composer.

Composer is a dependency manager for PHP. Composer manages the dependencies you require on a project by project basis. This means that Composer will pull in all the required libraries, dependencies and manage them all in one place. For Magento Commerce (Cloud), we use composer.json and composer.lock to manage your modules list, packages, dependencies, and so on for determining upgrades, patches, hotfixes, and more. Magento extension and module developers use composer.json to also manage their product installations and upgrades. For details, see Your project’s Composer files.

The following sections detail the specifics of Magento Commerce (Cloud) composer packages, how they work, and what they do within the code base.

For information on what files should and shouldn’t be in source control, see Project structure. We provide a .gitignore file to aid.

For Magento Commerce (Cloud) 2.2, the magento/magento-cloud-configuration (MCC) has been replaced by vendor/magento/ece-patches and vendor/magento/ece-tools. These packages decouple a patch update from a full product upgrade, allowing you to fully apply a patch without a full product installation or upgrade.

Your project’s Composer files

Your project root directory contains composer.json and composer.lock.

You edit composer.json to specify dependencies for your Magento Commerce (Cloud) project. For example, when you install an extension or module, you update composer.json to add the extension to the list. You can either edit it manually or the Component Manager can do it for you.

The file composer.lock stores a set of exact version dependencies that satisfy all of the version constraints of every requirement for every package in the dependency tree of the project.

The following commands determine what’s in composer.lock:

• composer update, which you must run every time you add or remove dependencies in composer.json. composer update updates composer.lock.
• composer install reads composer.lock, not composer.json, to download dependencies. You must keep an up-to-date copy of composer.lock in your Cloud Git repository.

The workflow is as follows:

1. Make a change to composer.json. For example, edit this file when installing an extension or module.
2. Run composer update.
3. Add composer.lock to or update it in your Cloud Git repository.
4. Push the changes to the Cloud environment, which causes Cloud to build and deploy the environment.

During the build phase, the Cloud environment runs composer install on a fresh clone of your Git branch to retrieve the latest dependencies.

Magento composer commands

We use the following commands for Magento:

• composer install: Use this command if you know extension and base code is updated. This command uses composer.lock, not composer.json. The command reads the lock file and checks the versions installed and listed in the file. If new lines are included or the file has a later version, the code is installed. After initial install, using the command only installs new code if you add new extensions or versions to composer.lock.
• composer update: Use this command when you need to perform complete updates of all extensions and base code. This command uses composer.json, not composer.lock.

Magento Commerce (Cloud) packages

The following sections discuss the Composer packages used by Magento Commerce (Cloud):

• vendor/magento/magento-cloud-metapackage
• vendor/magento/ece-patches
• vendor/magento/ece-tools
• vendor/magento/product-enterprise-edition

magento/magento-cloud-metapackage

vendor/magento/magento-cloud-metapackage should be the only package in the require section of your composer.json. This is a metapackage and does not contain any code.

The metapackage depends on the appropriate versions of vendor/magento/ece-patches, vendor/magento/ece-tools, and vendor/magento/product-enterprise-edition. At any given version, this package requires the same version of magento/product-enterprise-edition. For example, to use Magento Commerce version 2.2.0, for example, composer.json must specify a requirement for magento/magento-cloud-metapackage version 2.2.0.

This package depends on a floating version of vendor/magento/magento-cloud-configuration (abbreviated MCC). It depends on the major and minor version of MCC that correspond to the specified Magento Commerce version, and floats on the patch version so that compatible updates to this packages can be automatically pulled by running composer update.

vendor/magento/ece-patches