Composer 1 is dead – Upgrade to Composer 2 now

Composer has long been the de-facto dependency manager for PHP projects. It powers millions of applications, frameworks, and libraries by providing a reliable way to manage dependencies.

However, Composer 1 reached its end of life and is no longer maintained. If your project or CI pipeline is still using Composer 1, it’s time to upgrade.

What happens if your project still requires Composer 1?

If your composer.json specifies a constraint like ^1 for the Composer runtime, your build on Upsun will fail.
Here’s the kind of error you’ll see:

      Building application 'app' (runtime type: php:8.3, tree: 7760752)
        Generating runtime configuration.

        Installing build dependencies...
          Installing php build dependencies: composer
          W: Changed current directory to /app/.global/composer
          W: No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information.
          W: Loading composer repositories with package information
          W: Updating dependencies
          W: Your requirements could not be resolved to an installable set of packages.
          W:
          W:   Problem 1
          W:     - Root composer.json requires composer ^1, found composer[2.8.11] but it does not match the constraint.

How to check your Composer version

To check your current Composer version, execute the following:

composer --version

If you see Composer version 1.x.x, you are running the deprecated version.

How to upgrade your project to Composer 2

Upgrading is straightforward:

1. Update globally (recommended)

If Composer is installed globally on your system:

composer self-update --2

This will switch you directly to the latest stable Composer 2 release.

2. Install via Package Manager

For example, on macOS with Homebrew:

brew update
brew upgrade composer

3. Use the official installer

If you installed Composer manually:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --2
php -r "unlink('composer-setup.php');"

This will download Composer 2 locally into your project. You can move it globally if needed:

mv composer.phar /usr/local/bin/composer

Actions to take in your project

1. Update your composer.json

   Add a runtime API requirement to enforce Composer 2:

   "require": {
     "composer-runtime-api": "^2"
   }

2. Check your .upsun/config.yaml Ensure you declare Composer 2 in your .upsun/config.yaml configuration, or, as Composer version 2 is now the default version installed on every project, completely remove the Composer dependency:

   applications:
     app:
       dependencies:
         php:
           composer: "^2" # or remove this dependency as Composer v2 is the default

3. Test dependency resolution Run composer update with Composer 2 and commit the updated composer.lock. In rare cases, some legacy packages may need adjustments:

   Terminal

   composer update
   git add composer.lock 
   git commit "Update composer.lock"
   upsun push  

4. Update your CI/CD pipelines
   Check your Docker images, GitHub Actions, or other CI jobs. Many older PHP images still ship with Composer 1 by default.

   • For Docker, use the composer:2 official image.
   • For GitHub Actions, specify a step to upgrade Composer.

5. Communicate the change
   Update your project’s documentation to state that Composer 2 is required.

Troubleshooting common migration issues

Upgrading from Composer 1 to 2 is usually seamless, but you may encounter issues:

• API Rate Limits (GitHub, GitLab, etc.)
  Composer 2 uses parallel downloads which can trigger API rate limits. Solution: configure OAuth tokens for GitHub or GitLab in your auth.json.

• Plugins Not Compatible
  Some Composer plugins written for v1 may not work on v2. Ensure you update plugins to their latest version, or replace them if no update is available.

• Stricter Dependency Checks
  Composer 2 is stricter about dependency resolution. If you encounter errors, check your composer.json for constraints that need adjusting.

• CI/CD Caching Issues
  Clear your Composer cache in CI/CD environments (composer clear-cache) if builds fail after upgrading.

Conclusion

Composer 1 is officially unsupported. By upgrading to Composer 2, you get:

• Faster dependency resolution
• Modern PHP compatibility
• A safer, future-proof environment

Don’t wait until a dependency breaks or your pipeline fails—upgrade today.