Lock PHP Versions Across Environments with Composer’s config.platform

Why PHP Version Drift Matters

In a typical PHP project, each developer’s machine, the staging server, and the production host often run different PHP releases. Even a minor difference can cause a package that requires php >= 8.0 to be installed locally but omitted on a host running PHP 7.4. The result is a lockfile that looks good in one place but fails silently or throws runtime errors in another.

Thesis: Composer’s config.platform Emulates a Target PHP Runtime

The config.platform key in composer.json tells Composer to pretend that the PHP interpreter it’s running on matches the version you specify. During dependency resolution, Composer treats that version as the host, ignoring the actual runtime. This yields a lockfile that is reproducible across all environments that share the same config.platform setting.

Section 1 – What Is config.platform?

• Defined under config in composer.json or set via the CLI.
• Only affects the resolution phase of Composer; it does not change the PHP interpreter you run your code with.
• Typical syntax: { "config": { "platform": { "php": "7.4" } } }.

Section 2 – Why Use It?

• Reproducible lockfiles – every machine sees the same set of packages.
• Prevents accidental installation of packages that require a newer PHP version than your target environment.
• Helps teams lock the environment before pushing to CI or production.

Worked Example

Suppose your production server runs PHP 7.4, but your local machine is on PHP 8.1. You want all developers and CI to install dependencies as if they were on 7.4.

1. Open composer.json and add the platform key:

   {
     "require": {
       "symfony/console": "^5.4"
     },
     "config": {
       "platform": {
         "php": "7.4"
       }
     }
   }

2. Run composer update locally. Composer will resolve dependencies as if PHP 7.4 is running, even though the CLI is PHP 8.1.

   composer update

3. Commit the updated composer.lock to version control.
4. In your CI pipeline, ensure the same config.platform is present (or set the environment variable COMPOSER_PLATFORM_PHP=7.4) before running composer install.

Result: The lockfile contains packages compatible with PHP 7.4, and all environments install the same set.

Trade‑Offs and Limitations

• The setting only influences Composer’s dependency resolution; it does not downgrade or upgrade the actual PHP interpreter used at runtime.
• Running the application on a newer PHP (e.g., 8.1) can still expose API changes if your code or dependencies rely on features removed in 7.4.
• Setting a lower PHP version may silently exclude packages that truly need a newer PHP, potentially breaking functionality that only manifests under certain conditions.
• Composer 1.x is End‑of‑Life; config.platform is guaranteed only in Composer 2.x and above.
• Keep the config.platform entry under version control so every team member and CI job uses the same constraints.

Actionable Checklist

1. Add config.platform.php to composer.json with your target PHP version.
2. Run composer update locally and commit the lockfile.
3. Configure your CI environment to use the same composer.json (or export COMPOSER_PLATFORM_PHP).
4. Test the application on the highest PHP version you expect to run on production to catch any API mismatches early.
5. Document the platform configuration in your project README so new contributors understand the enforced PHP version.

Conclusion

Composer’s config.platform is a lightweight, declarative way to enforce a consistent PHP runtime across all stages of your workflow. By pinning the platform version, you eliminate the “works on my machine” syndrome caused by PHP version drift, while still allowing your code to run on newer interpreters when appropriate. Add it to your composer.json, update, and test – your dependency graph stays stable, and your team stays productive.