Himanshu SharmaSoftware engineer
Let’s talk

Composer · Lesson 6 of 15

Composer constraints: caret, tilde, wildcards and stability

Read Composer version ranges and stability rules without treating compatibility notation as a guarantee of working code.

12 minManaging dependenciesUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonExplain caret, tilde and wildcard constraints and reject incompatible local release ranges.

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:

text
^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 series

This 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:

bash
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-run

In 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.

Check yourself

1. Which stable release fits ^0.3?
2. Which stable release fits ~1.2.3?
3. Does prefer-stable allow every development version?