Aligning Composer Constraints with Your README

When you maintain a PHP package, composer.json and the README tell different audiences about compatibility. Composer uses the version constraints in composer.json to decide which package versions it can install. The README tells people which PHP versions the package supports and how to set it up.

Keep both files consistent with the same support policy. Say whether you mean versions Composer allows, versions you test, or versions the project officially supports. Composer does not compare README prose with its constraints, so a valid composer.json can still sit beside outdated or conflicting documentation.

Separate declared, tested, and supported versions

A Composer constraint sets which versions Composer may consider when choosing versions for the packages being installed. Composer calls this choice dependency resolution. For example, Composer documents ^1.3.2 as a range starting at 1.3.2 and below 2.0.0; the exact meaning of a constraint depends on its operators and version range rules. The php platform requirement lets a package declare which PHP versions it requires.

The maintainer may test selected PHP versions while declaring a wider compatible range, so the declared range does not show which versions were tested. The README should name the kind of claim it makes. “Composer permits PHP versions in this range” describes declared compatibility; “CI tests these versions” describes test coverage; “We support these versions” communicates the project’s support policy. Use those terms consistently rather than presenting different ranges as competing answers.

A broad constraint also needs evidence from testing. Composer recommends that library maintainers run dependency checks with both composer update and composer update --prefer-lowest. The first tests with newer allowed dependency versions, while the second checks the lowest versions allowed by the package’s constraints. Projects that install a library do not use its lock file. Testing only the versions listed there does not cover the combinations those projects install. See Composer’s guidance for testing library dependencies.

Update the README when support changes

When a PHP requirement changes, update the php entry in composer.json and the README support or installation wording in the same change. If the README describes a narrower tested range than Composer declares, label it as tested rather than implying that Composer enforces that narrower range.

For example, a README that says “PHP 8 supported” may leave users unsure whether every PHP 8 release is included. Compare the statement with the actual constraint and clarify its scope in plain language. If the project has a specific tested range, state that range separately from the Composer requirement.

The README is public information about the package. Composer’s schema includes a readme field, and Packagist uses GitHub’s README API for packages hosted on GitHub. But Composer treats the support statement as prose. It does not interpret that sentence as an installation rule or verify that it matches composer.json, as the schema documentation makes clear.

Check metadata and runtime behavior separately

Run composer validate --strict before committing metadata changes and before tagging a release. Composer’s validate command checks the JSON and, when a lock file exists, whether it matches the manifest. The --strict option also makes warnings return a non-zero exit code. A successful result does not mean the README agrees with the constraint.

During a release review, compare the README’s support statements with the Composer requirement. If you want automated drift checks, keep the support range in a structured value that a project-specific check can compare with the manifest. Avoid relying on a general-purpose text search to understand prose, since wording can change without changing the support policy.

Test the PHP versions the project intends to support, including the ends of that range. Run dependency jobs with both regular and lowest allowed versions. Composer’s check-platform-reqs command checks the actual PHP runtime and installed extensions against package requirements; it ignores config.platform, which can otherwise influence dependency resolution. That check verifies declared platform requirements, while the test suite checks package behavior. Neither establishes that every README claim is accurate.

Mismatches leave users guessing

When the README claims broader support than the constraint allows, Composer rejects the installation for users who follow the documentation. When the constraint allows a version the README calls unsupported, Composer can resolve dependencies while the user wonders whether the restriction is intentional or outdated.

A constraint that is narrower than the package’s actual compatibility also blocks users from installing it on environments Composer excludes. Conversely, a constraint that is too broad can admit environments the maintainer has not tested. Composer uses declared requirements when it chooses package versions. These outcomes explain what a mismatch does, but not how often mismatches occur.

A discrepancy is not automatically a defect. A project can intentionally test or recommend a narrower range than it declares as compatible. The documentation should identify that distinction so users know what Composer will permit and what the maintainer has actually verified.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com