Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.upsun.com/llms.txt

Use this file to discover all available pages before exploring further.

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 or Platform.sh 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: 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 Update the required PHP version and add a runtime API requirement to enforce Composer 2: 
    {
    "require": {
      "php": ">=8.2",
      "composer-runtime-api": "^2"
    }
}
    Your current PHP version is maybe outdated?
    Composer 2 requires at least PHP 7.2.5, but many modern packages no longer support versions below PHP 8.1. To ensure long-term compatibility, security, and access to the latest ecosystem improvements, we strongly recommend upgrading to PHP 8.2 or higher.
  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: 
    composer update
git add .upsun/config.yaml composer.lock
git commit "Update Composer to version 2"
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.
Last modified on April 30, 2026