Install, manage, and upgrade extensions

This information includes information for adding extensions to Magento Commerce Cloud, managing enabled and disabled extensions, and upgrading extension code.

When adding extensions to Magento Commerce Cloud, you should add the code to a Git branch, test in Integration, deploy and test in Staging, before finally pushing and using in Production.

Extensions include the following:

  • Modules to extend Magento capabilities, with options through Magento Marketplace and directly through company sites
  • Themes to change the look and feel of your storefronts
  • Language packages to localize the storefront and Admin

These instructions walk through extension installation purchased from Magento Marketplace. You can use the same procedure to install any extension with the extension’s Composer name. To find it, open the extension’s composer.json file and note the values for "name" and "version".

We also include instructions for updating extensions.

Create a branch for adding or updating the extension

We recommend using a branch for adding or updating, configuring, and testing your extension.

  1. Log in to your local development system, or switch to, the Magento file system owner.
  2. Change to a directory to which the Magento file system owner has write access.
  3. Enter the following command in a terminal to log in to your project:

    1
    
     magento-cloud login
    
  4. List your projects. With the project ID, you can complete additional commands.

    1
    
     magento-cloud project:list
    
  5. If necessary, clone the project to your local. You should have cloned when setting up your local development workspace.

    1
    
     magento-cloud project:get <project ID>
    
  6. Change to a project directory. For example, cd /var/www/html/magento2
  7. List environments in the project. Every environment includes an active Git branch of your code, database, environment variables, configurations, and services.

    1
    
     magento-cloud environment:list
    

    magento-cloud environment:list—displays environment hierarchies whereas the git branch command does not.

  8. Fetch origin branches to get the latest code:

    1
    
     git fetch origin
    
  9. Check out, or switch to, a specific branch and environment. Git commands only checkout the Git branch. The Magento Cloud command also switches to the active environment.

    1
    
     magento-cloud environment:checkout <environment ID>
    

    To create a new environment, use magento-cloud environment:branch <environment name> <parent environment ID>

  10. Pull any updated code to your local for the environment ID (which is the Git branch):

    1
    
     git pull origin <environment ID>
    
  11. Create a snapshot of the environment as a backup:

    1
    
     magento-cloud snapshot:create -e <environment ID>
    

Install an extension

Extension installation uses the following steps:

  1. Purchase an extension or module from Magento Marketplace or another site.
  2. Create a branch to work with the files.
  3. Get the extension’s Composer name and version from your purchase history.
  4. In your local Magento Commerce Cloud project, update the Magento composer.json file with the name and version of the extension and add the code to Git. The code builds, deploys, and is available through the environment.
  5. Verify the extension installed properly.

Step 1: Get the extension’s Composer name and version

If you already know the extension’s Composer name and version, skip this step and continue with Update Magento’s composer.json.

This section discusses how to get a module’s Composer name and its version from Magento Marketplace. Alternatively, you can find the name and version of any module (whether or not you purchased it on Marketplace) in the module’s composer.json file. Open composer.json in a text editor and write down the values of "name" and "version".

To get the module’s Composer name from Magento Marketplace:

  1. Log in to Magento Marketplace with the username and password you used to purchase the component.
  2. In the upper right corner, click <your username> > My Account as the following figure shows.

    Access your Marketplace account

  3. On the My Account page, click My Purchases as the following figure shows.

    Marketplace purchase history

  4. On the My Purchases page, click Technical Details for the module you purchased as the following figure shows.

    Technical details shows the module's Composer name

  5. Click Copy to copy the component name to the clipboard.
  6. Open a text editor.
  7. Paste the module name in the text editor.
  8. Append a colon character (:) to the component name.
  9. In Technical Details on the My Purchases page, click Copy to copy the version to the clipboard.
  10. Append the version number to the component name after the colon.

    A sample follows:

    1
    
     pixlee/magento2:1.0.1
    

Step 2: Update Magento’s composer.json

When adding the module to composer.json, the file app/etc/config.php will also be updated. This file includes a list of installed modules, themes, and language packages, shared configuration settings. This file also includes Configuration Management (Pipeline Deployment) values too.

To update composer.json:

  1. If you haven’t done so already, change to your environment root directory.
  2. Enter the following commands to update it:

    1
    
     composer require <component-name>:<version> --no-update
    
    1
    
     composer update
    

    For example:

    1
    
     composer require pixlee/magento2:1.0.1 --no-update
    
    1
    
     composer update
    
  3. Wait for project dependencies to update.
  4. Enter the following commands in the order shown to commit your changes, including composer.lock:

    1
    
     git add -A
    
    1
    
     git commit -m "<message>"
    
    1
    
     git push magento <environment ID>
    

If there are errors, see extension deployment failure.

When installing and adding the module, you must add the composer.lock to your Git branch for deployment. If the extension is not in the file, the extension won’t load in Magento Commerce Cloud. This ensures when the composer install command is used, the extension properly loads. This command uses the composer.lock file.

Step 3: Verify the extension

To verify the extension installed properly, you can check its functionality in the Magento Admin or you can view enabled modules using the CLI:

  1. Open a terminal.
  2. Checkout the branch where the module is installed.
  3. List all enabled modules:

    1
    
     php bin/magento module:status
    
  4. Verify the extension is listed.

The extension name is in the format <VendorName>_<ComponentName>. It will not be in the same format as the Composer name.

Manage extensions

To manage your extensions, you can enable and disable or change settings per environment.

Enable and disable extensions

To enable or disable extensions, you must begin those changes on your local in a branch. You should never enable or disable extensions directly on your environments. These instructions assume you have config.php in your Git branch and implementation. If you do not use Configuration Management or config.php, we strongly recommend you do.

Trying to enable and disable extensions not following this method can lead to permissions and other issues.

  1. Work in a branch to update config.php.
  2. In a terminal, access your local development environment.
  3. List all module.

    1
    
     php bin/magento module:status
    
  4. Enable a module.This command updates the config.php file with the enabled status of the module.

    1
    
     php bin/magento module:enable <module name>
    
  5. Disable a module. This command updates the config.php file with the disable status of the module.

    1
    
     php bin/magento module:disable <module name>
    
  6. Verify the status of a module:

    1
    
     php bin/magento module:status
    
  7. Push your updates to the Git branch.
  8. Complete deployment to Integration for testing, then Staging for testing, and finally Production.

Modify configurations

You update configurations according to Configuration Management for config.php.

Upgrade an extension

You should have a branch to work in when updating your extension. These instructions use composer to update the files. Before you continue, you must:

  • Know the extension’s Composer name and version
  • Know the extension is compatible with your project and Magento Commerce Cloud version. In particular, check the required PHP version.

To update an extension:

  1. If you haven’t done so already, change to your environment root directory.
  2. Open composer.json in a text editor.
  3. Locate your extension and update the version.
  4. Save your changes to composer.json and exit the text editor.
  5. Update project dependencies:

    1
    
     composer update
    
  6. Enter the following commands in the order to commit the changes and deploy the project, including composer.lock:

    1
    2
    3
    
     git add -A
     git commit -m "<message>"
     git push origin <environment ID>
    
  7. Wait for the project to deploy and verify in your environment.

If there are errors, see Component deployment failure.