Composer tips and tricks

Last update: 2023-09-29
  • Created for:
  • Experienced
    Developer

You may encounter issues when developing Adobe Commerce modules with Composer. These best practices describe some common tasks to make development easier and help you quickly resolve issues.

NOTE

These guidelines apply primarily to global reference architecture (GRA) projects.

Speed up Composer

Install https://github.com/hirak/prestissimo to speed up Composer with asynchronous package downloads.

composer global require hirak/prestissimo

If you encounter problems, uninstall prestissimo:

composer global remove hirak/prestissimo

Resolve vague versioning issues

Composer sometimes gets deadlocked with package versions. You may see messages about versions that are incompatible even if they are not. Before debugging compatibility issues, try resetting Composer:

  1. Clear the Composer cache.

    composer clearcache
    
  2. Remove the composer.lock file for all packages.

    rm -rf vendor/* composer.lock
    
  3. Reinstall the Composer packages.

    composer install
    
TIP

These steps update all packages to the latest available version. Revert the composer.lock file from Git to undo these upgrades.

Check for possible updates in client packages

  1. Find out which packages might be outdated.

    composer outdated
    
  2. Filter using wildcards and/or the --minor-only option to skip backward-incompatible upgrades:

    composer outdated 'magento/*'
    composer outdated --minor-only 'magento/*'
    

Find out if a module is installed

View details about all installed packages on a Git branch.

composer info

Run composer install after switching Git branches and before running composer info. Otherwise, Composer shows details about the previous branch that you had checked out.

TIP

To filter or search, use one of the following commands.

composer info '*magento*'
composer info | grep magento

Find out why a (specific version of a) package is installed

Sometimes, Composer installs the latest available version of a package because of a strict dependency in another package.

Find out if there is a strict dependency in another package.

composer why client/module-example

If the results show a list of metapackages or another package that is not explicitly required, run the command on that package:

composer why example/metapackage

Find out why a package is not installed

Sometimes, Composer does not install a package because it conflicts with another package, another package replaces it, or you haven’t defined it is as a dependency.

Find out why a package is not installed.

composer why-not client/module-example

Host a private Composer repository

If you require a private Composer repository, use Private Packagist or JFrog Artifactory. Do not use Satis.

  • Private Packagist is secure, costs around $600 USD per year with three admin users and is hosted.

  • JFrog Artifactory starts at $1,176 USD per year. It is not as commonly used as Packagist, but it supports more languages than PHP.

  • Satis has no built-in security, no automation, and requires additional hosting. It is only free if your time is also free.

Versioning packages

Use Semantic Versioning 2.0.0 as described in the Adobe Commerce versioning schema. Do not reinvent the wheel.

For Adobe Commerce module dependencies, follow the module version dependencies documentation.

Do not use the version definition inside the composer.json file. Instead, use Git tags for versions. See Composer Versions and constraints.

Where to put modules that come in an archive file and not through Composer

Create a Git repository for modules in an archive and host them yourself. Every Adobe Commerce module has a composer.json file. After you host it in Git and synchronize it with Private Packagist, you can install it with Composer.

When you receive a new version of the package, upload the code to Git, tag it, and install the new version with Composer.

On this page