After this lesson you can read common Composer constraints and explain why a package may be rejected even when its name is correct. You will test ranges against the one release supplied by the local book-label repository.
A constraint is a set of acceptable versions
A package name chooses the dependency; the constraint chooses which versions may satisfy it. Composer must find a selection satisfying all relevant requirements together. An individual constraint can look reasonable while the combined graph has no valid solution.
A release's version is not a guarantee of compatibility. Constraint conventions express your intended policy and depend on package maintainers following a meaningful release policy. Behaviour checks remain necessary after an accepted update. Do not equate a compatible-looking number with proof that an application still works.
For stable versions, these examples show useful boundaries:
^1.2.3 at least 1.2.3, below 2.0.0
^0.3 at least 0.3.0, below 0.4.0
^0.0.3 at least 0.0.3, below 0.0.4
~1.2.3 at least 1.2.3, below 1.3.0
~1.2 at least 1.2.0, below 2.0.0
1.2.* stable releases in the 1.2 seriesThis is an explanatory range table, not command output. Composer's official Versions and constraints documentation defines the operators and their pre-release handling. Notice that a caret before version one does not mean all future zero-major releases. The first significant nonzero component becomes especially important.
Compare caret and tilde deliberately
Caret is useful when you intend to accept later compatible releases under a package's versioning policy. Tilde with a patch component is more restrictive about minor releases. Neither operator is universally safer: a narrow range can delay useful fixes, while a broad range can expose changes your tests do not cover.
Choose a range you can explain to a reviewer. Avoid copying a constraint from an unrelated project whose PHP version and maintenance schedule differ. An exact version can be appropriate for a deliberate pin, but remember that an application's lock already records exact selections while the manifest communicates allowed future resolution.
Wildcards are readable for a release series, but an unrestricted wildcard gives little guidance about compatibility. It does not make migration work disappear. Prefer an intentional boundary for a dependency with a public API you rely on.
Verify a local range without keeping changes
Run these commands in the shop that offers local version 1.0.0:
composer require "course/book-label:~1.0.0" --dry-run
composer require "course/book-label:1.0.*" --dry-run
composer require "course/book-label:^0.3" --dry-runIn the captured Composer 2.10.2 runs, the first two commands exited successfully. The third exited with dependency-resolution status 2 because the repository only offered 1.0.0. These are controlled outcomes for this fixture, not predictions about packages in a changing public catalogue.
A dry run lets you inspect the intended operation without retaining its changes. It is not a sandbox for arbitrary untrusted project configuration. Review scripts and plugins before running Composer in unfamiliar source trees. For this course, the manifests are fully visible and locally authored.
Understand stability as another decision
Composer distinguishes stable releases from development and pre-release versions. The root project's minimum stability governs eligibility unless a more specific allowed stability applies. A prefer-stable setting expresses a preference among eligible choices; it is not the same as permitting every development branch.
Do not lower project-wide stability merely because one package uses a development branch. Investigate the package and, if appropriate, use a narrowly justified explicit requirement. A moving branch may change without the release discipline you expect from a tagged version. Our path fixture supplies a stable version explicitly to avoid accidental dependence on branch naming.
A separate local metapackage fixture was also used to test these boundaries without downloading source. It offered releases on both sides of the documented limits. Resolution selected 0.3.9 for the caret zero-minor range, 1.2.9 for the patch-level tilde range and 1.9.0 for the broader major-one ranges. Those are synthetic fixture versions, not real public package releases.
Common mistakes
Writing ^0.3 while expecting 0.4 is a boundary mistake. Writing ~1.2 while intending only patch releases is another. Read each operator with the number of components actually present.
Do not run an update repeatedly hoping it will override incompatible constraints. Read the reported requirements and decide which policy or code needs to change. Dependency resolution is a constraint problem, not a lottery.
Exercise
You need stable versions from 1.2.3 up to, but excluding, 1.3.0. Choose between caret and tilde forms, then explain why the other common form is broader.
Show the answer
Use ~1.2.3. The form ^1.2.3 permits later stable releases below 2.0.0, including later minor series. A lock may currently select the same release under either constraint, but a future update can reveal the difference.
Continue learning
Previous: Composer install versus update: choosing a deliberate change
Next: Composer PSR-4: loading the bookshop library
Related: Composer manifests and locks: intent versus resolution
Related: Composer packages: path repositories, Git tags and publishing
Key points
- Caret ranges become narrower before version one.
- Tilde boundaries depend on how many version components are written.
- Stability eligibility and version compatibility are separate filters.