How Cloud Uses Composer

This topic discusses how we use Composer to manage dependencies and upgrades in Magento Enterprise Cloud Edition, and provides context about the packages that comprise Cloud, what the packages do, and how they fit together.

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 Enterprise Cloud Edition project. (For example, when you install an extension, you update composer.json. 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.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.

    Therefore, 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, install an extension).
  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 Enterprise Cloud Edition packages

The following sections discuss the Composer packages used by Magento Enterprise Cloud Edition:

magento/magento-cloud-metapackage

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 magento/magento-cloud-configuration and magento/product-enterprise-edition. At any given version, this package requires the same version of magento/product-enterprise-edition. Therefore, to use Magento EE version 2.1.4, for example, composer.json must specify a requirement for magento/magento-cloud-metapackage version 2.1.4.

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

magento/magento-cloud-configuration (MCC)

This package contains the following scripts and magento commands that automatically perform building and deployment of the codebase on the cloud environment:

  • pre-deploy.php
  • bin/magento magento-cloud:deploy
  • bin/magento magento-cloud:build

magento/magento-cloud-configuration also contains patch files that are specific to Cloud.

There is a many-to-one relationship between the MCC version and Magento versions.

For Magento EE, versions are specified as 2.<x>.<y>.

MCC versions are specified as: <100 + x>.<y>.*. For example, Magento EE 2.1.4 is associated with MCC 101.4.0. Subsequently, a new version of MCC could be released that corresponds to the same Magento EE version, and it would be 101.4.1.

We release updated MCC code to add a new patch or to improve the build and deploy hooks.

magento/product-enterprise-edition

This metapackage requires Magento application components, including modules, frameworks, themes, and so on.

Base packages and file marshaling

Magento contains two base packages, magento/magento2-base and 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 Enterprise Cloud Edition 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 marshaling 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:

  1. Run composer update locally

    The new version of the base packages are marshaled out into the Cloud project root directory, which means files are added, removed, and changed.

    File marshaling works on your local system but not on the Cloud server.

  2. Add and commit these updated files to your Cloud Git repository.
  3. Push the changes to your Cloud integration environment.

For more information, see Test a Magento patch.

This makes sure that base files are placed in the correct location and are under source control. If you notice any problems after a 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.