Download the PHP package ctw/ctw-composer-plugin-composerlenientplugin without Composer

Composer Lenient Plugin

Install Composer packages that cap their php requirement on a newer PHP — without --ignore-platform-req, without forking, and without editing anything in vendor/.

ctw/ctw-composer-plugin-composerlenientplugin is a Composer 2 plugin that relaxes the upper bound of the php platform requirement for an explicit allowlist of packages, at dependency-solver pool-build time. It lets a package that is capped at, say, ~8.4.0 install cleanly on PHP 8.5, 8.6, and later, while every other platform check stays fully enforced and your real PHP version is never faked.

Since 2.x the same mechanism widens any package requirement, not only php — for example letting a package that declares laminas/laminas-servicemanager: ^3 also resolve against ^4 while upstream finishes a not-yet-released major bump. php and package requirements share one uniform config format; see Configuration below.

Does this fix your problem?

If composer install or composer update fails on a newer PHP with a message like this:

…then yes. The package's code runs fine on your PHP, but its declared php constraint has an upper bound (~8.4.0, <8.5, ^8.0 <8.5, etc.) that Composer refuses to cross. The same failure happens with a ~8.3.0-capped package on PHP 8.4, a ~8.5.0-capped one on PHP 8.6, and so on for every future PHP release.

This plugin removes that specific blocker for the packages you trust — and only those packages.

Why not just use the usual workarounds?

This plugin does the job generically and declaratively: name the packages once, and it widens their php constraint to original || ^8.5 in memory during dependency resolution.

How it works

The plugin subscribes to Composer's PrePoolCreateEvent. As the solver builds its candidate package pool, the plugin finds each allowlisted package and replaces its php link with original || <allow> (default ^8.5), preserving the original lower bound. Aliases are unwrapped so the change lands on the real package definition.

Because this happens during composer update, the widened constraint is written straight into composer.lock. Every later composer install (deploys, CI, teammates) then reads the relaxed constraint from the lock and passes the platform check with no flag at all.

Packages that genuinely require a newer PHP than you have still fail to resolve, exactly as they should — only the names you list are touched.

Requirements

• PHP >= 8.4
• Composer 2 (composer-plugin-api ^2.0)

Installation

A Composer plugin must be allow-listed before Composer will execute it:

Configuration

Configuration is a list of rules in your root composer.json extra block, namespaced under ctw. Every rule has the same shape — php is just another requirement, so there is no special case and no default; set all three keys explicitly:

Each rule has three keys, all required:

A rule missing any key — or whose packages list is empty — is ignored.

The first rule above widens the php constraint of five packages capped at ~8.4.0 so they install on PHP 8.5. The second turns laminas/laminas-form's declared laminas/laminas-servicemanager: ^3.22.1 into ^3.22.1 || ^4.0 in memory, so a servicemanager-4 stack resolves without forking the package. In both cases the original lower bound is preserved, the widened constraint is baked into composer.lock, and packages outside a rule's packages list are untouched.

Tip: list transitive dependencies explicitly. If a package such as laminas/laminas-mail is pulled in by another dependency rather than by your own require, it must still appear in a rule's packages or it will block resolution.

Use with care: widening a non-php requirement only changes resolution — it does not make incompatible code work. Use it when you have evidence the package already runs against the newer version (for instance, upstream's own CI exercises it on an unreleased branch), and remove the rule once a properly-tagged release ships.

See also: README_LAMINAS.md — a real-world walkthrough of using this plugin to run five Laminas packages on PHP 8.5, including how it compares to the alternatives.

Bootstrapping (first install only)

A plugin cannot rewrite the solver pool until it is itself installed and active, so the very first update — the one that physically installs this plugin — still needs the flag once:

After that, every composer install and composer update runs without --ignore-platform-req, because the relaxed php constraint already lives in the lock file.

Verifying

After the second update, the lock carries the widened constraint:

Run an update with -v to see exactly what was relaxed:

FAQ

Why does composer install say "your php version does not satisfy that requirement" on a newer PHP, even though the library works? Because the library declares an upper bound on php (for example ~8.4.0), and Composer enforces it literally. The code may be compatible, but Composer will not cross a declared cap.

How do I install a package that does not officially support my PHP version? Add the package to this plugin's packages allowlist and run composer update. The plugin widens only that package's php constraint; nothing else changes.

Is this safe? Does it patch files in vendor/? No files are patched. The change is made in memory during dependency resolution and recorded in composer.lock. Your real PHP version is never spoofed, and every other platform requirement (extensions, other packages' php) stays enforced.

Does it affect deploys and CI? Yes — positively. Because the relaxed constraint is baked into composer.lock, deploy and CI runs use a plain composer install with no --ignore-platform-req flag.

Can I use it for the next PHP, like 8.6 or 8.7? Yes. Set "allow": "^8.6" (or whatever you need). The default is ^8.5, which permits 8.5 through the 8.x line but stops before 9.0, since a major release may introduce breaking changes.

Testing

The suite builds real Composer\Package objects and asserts the relaxed php constraint with Composer\Semver\Semver, so it exercises actual Composer semantics rather than mocking the constraint logic.

Caveats

• The plugin only widens a requirement, and only by an OR (|| <allow>). It never narrows or removes a constraint.
• Widening a non-php requirement changes only resolution; it cannot make incompatible code work. Use such a rule only when the package already runs against the newer version, and drop it once a tagged release ships.
• Only the packages a rule names are affected; every rule's allowlist is deliberately explicit.
• Rules target tagged upstream releases. Branch/dev aliases are out of scope, as the affected packages resolve to plain tags.

Keywords

Composer plugin · ignore-platform-req alternative · your php version does not satisfy that requirement · install package on PHP 8.5 / 8.6 · relax php platform constraint · php upper bound · unsupported PHP version · config.platform.php alternative · force composer install on newer PHP · --ignore-platform-reqs.

License

See LICENSE.md.