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.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-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 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.
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 update, which you must run every time you add or remove dependencies in
composer.json, to download dependencies. You must keep an up-to-date copy of
composer.lockin your Cloud Git repository.
The workflow is as follows:
- Make a change to
composer.json. For example, edit this file when installing an extension or module.
composer.lockto or update it in your Cloud Git repository.
- 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.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 update: Use this command when you need to perform complete updates of all extensions and base code. This command uses
Magento Commerce (Cloud) packages
The following sections discuss the Composer packages used by Magento Commerce (Cloud):
Refer to Composer package updates for release information.
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/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
This package contains patch files that are specific to Magento Commerce (Cloud). Patches are separate from tools, allowing you to apply patch updates without requiring a full upgrade and install of all Magento Commerce (Cloud) code. Using
composer update automatically runs tools to check for available patches and to run them with build and deploy scripts.
Versions are specified as
These updates strictly contain improvements to Magento Commerce (Cloud). Patches are available in the
vendor/magento/ece-patches folder. To check for available patches, you can check in the
The Cloud tools package, also known as ece-tools, is compatible with Magento version 2.1.4 and later to provide a rich set of features you can use to manage your Magento Commerce project. It contains scripts and Magento Commerce (Cloud) commands designed to help manage your code and automatically build and deploy your Cloud projects.
You can list the available Cloud tools commands using:
php ./vendor/bin/ece-tools list
The following updates describe the latest improvements to the Cloud tools package, which update as needed through patching and product upgrades managed by the
magento-cloud-metapackage. The Cloud tools package adheres to the version sequence:
This metapackage requires Magento application components, including modules, frameworks, themes, and so on.
Base packages and file marshalling
Magento contains two base packages,
magento/magento2-ee-base. These packages contain interstitial files that cannot be classified as extensions, themes, frameworks, or language packages; for example, sample server configuration files, PHP
entry points, and so on.
These files are location-dependent, and cannot reside in the
vendor directory. They are distributed as part of the base packages, and they rely on hooks located in the
magento/magento-composer-installer package, which marshals them to the appropriate locations.
One way in which Magento Commerce (Cloud) deploys differently than other Magento installations is that it does not marshal base packages on the Cloud environment. This could change in a future Cloud release, but for now, on the Cloud environment specifically, the marshalling functionality of
magento/magento-composer-installer is disabled.
Therefore, when upgrading to a new Cloud version or adding, removing, or changing any packages that rely on file marshaling, you must:
The new version of the base packages are marshalled out into the Cloud project root directory, which means files are added, removed, and changed.
File marshalling works on your local system but not on the Cloud server.
- Add and commit these updated files to your Cloud Git repository.
- Push the changes to your Cloud Integration environment.
For more information, see Patch Magento Commerce (Cloud).
This makes sure that base files are placed in the correct location and are under source control. If you notice any problems after deploying an updated version of Magento, one of the first things to check should be whether all of the base package files were added to source control.