The platform setting tells Composer to pretend your PHP version and extensions are something specific while it resolves packages. The platform-check setting makes the generated autoloader verify the real runtime. One shapes what gets installed, the other catches a mismatch at runtime.
What each setting does
| Setting | Purpose | Default |
|---|---|---|
| platform | Fake PHP and extension versions for resolution | Empty, uses the real machine |
| platform-check | Create a check file that verifies the runtime | php-only |
The Composer docs describe platform as letting you fake platform packages. Setting an extension to false hides a locally installed extension from Composer. They add a caveat: dependencies are then no longer checked accurately, so running check-platform-reqs is recommended.
For platform-check, the default checks only the PHP version. Setting it to true also checks that extensions are present. Setting it to false stops Composer creating the platform_check.php file at all.
Why this is a security topic
Platform settings decide which package versions can be chosen. If your lock file was resolved against PHP 8.3 but production runs an older, unsupported PHP, you may be running dependency versions that were never tested together, on a runtime that no longer gets fixes. Pinning the platform to your real production version keeps resolution honest.
Steps to configure it well
- Set the platform PHP version to match production, not the newest on your laptop.
- Keep platform-check on at least php-only. Consider true if extensions matter to you.
- Before each deploy, run the platform requirements check against the lock file.
- Fail the build when it reports a mismatch.
composer check-platform-reqs --lock --no-dev
The lock option checks requirements from composer.lock rather than from installed packages. The docs also note that this command ignores your platform config, which is the point: it tests the real requirements, not the pretend ones.
Common mistakes
- Faking a newer PHP version to make an install pass, then running older PHP in production.
- Turning platform-check off to silence an error, which removes the safety net.
- Checking only on a developer machine, which may have extra extensions installed.
Try it yourself
Click through it at your own pace, or open it full screen. Watch how drift between the inventory and the running system gets flagged.
Where Safeguard fits
Safeguard's policies and gates can check dependency changes in a pull request before merge. A free scan shows what it finds today.
Quick check
Does platform-check slow down my application?
Composer generates a small check file that runs at autoload time. If you want to skip it, the setting can be false, but then you lose the runtime guard.
Should the platform setting match production?
Yes. Otherwise the lock file may contain versions chosen for a runtime you do not use.
Sources
Last reviewed: 19 October 2026.
