In a composer.json, how do minimum-stability, prefer-stable and a stability flag like @beta decide whether Composer may install an unstable release?

## Stabilities as Composer sees them Every version Composer knows has a **stability**, taken from its suffix: - `1.1-BETA` is `beta`, `1.1-RC1` is `RC`, `1.1` (no suffix) is `stable`. - Branches are always `dev`: a version-like branch `1.x` becomes `1.x-dev`, and any other branch such as `main` becomes `dev-main`. The order, from least to most stable, is **`dev`, `alpha`, `beta`, `RC`, `stable`**. Three separate knobs decide which of these the solver may pick. ## `minimum-stability`: a floor for every package `minimum-stability` is a **root-only** property of `composer.json`. It **defaults to `stable`**. Every version of every package that is less stable than the floor is removed from consideration before the solver runs. With the default, a project cannot get `2.0-beta.1` of anything, no matter how the constraint is written, unless it relaxes the rule somewhere. ## Stability flags: an exception for one package A **stability flag** is written after the constraint with `@`, in `require` or `require-dev` of the root package: ```json { "require": { "acme/sdk": "^2.0@beta", "acme/fixtures": "@dev" } } ``` - `^2.0@beta` means: the range `^2.0`, and for this package accept `beta`, `RC` and `stable` releases. - `@dev` with an empty constraint means: any version of this package, including dev branches. Flags are **root-only**. That produces the classic surprise: your project requires a package whose own `composer.json` asks for `"acme/data": "dev-main"`. The flag implied by `dev-main` counts only in the root, so resolution fails until you **also** list `"acme/data": "@dev"` in your own `require`. Composer's schema documentation shows exactly this case. ## `prefer-stable`: a preference, not a filter `prefer-stable: true` (also root-only, off unless set) changes the **choice**, not the **allowed set**. When both a stable and an unstable release satisfy the constraints, Composer takes the stable one. If only a dev version or only alphas exist for a package, they are still selected, provided `minimum-stability` allows them. The CLI can also pass `--prefer-stable` for a single `update` or `require`. | Setting | Scope | Default | Effect | |---|---|---|---| | `minimum-stability` | all packages | `stable` | removes less stable versions | | `@beta`, `@dev`, … flag | one package | none | lowers the floor for that package | | `prefer-stable` | all packages | off | picks stable when both fit | ## The two common configurations 1. **Stable floor, targeted flags** (`minimum-stability` left at `stable`, a flag on the one package you need early). Everything else stays stable; the exception is visible in review and disappears when you remove the flag after the stable release ships. 2. **`"minimum-stability": "dev"` with `"prefer-stable": true`**. Popular in project skeletons, it lets any package fall back to a dev version when no stable release satisfies the constraints. The risk is silence: a constraint that stops matching any stable release makes Composer pick a dev branch instead of failing, and the lock file records it without anyone deciding. Interviewers usually want to hear why the first is safer for production applications. ## Reading the failure When the floor removes the only matching versions, Composer's problem report says so explicitly: the root `composer.json` requires the package with your constraint, it **found** candidate versions, but they **do not match your minimum-stability**. That wording is the tell. The fix is almost never to lower the floor globally; it is one of: - add a stability flag to that one package in the root, such as `^2.0@beta`; - if the unstable version is demanded by a dependency, add that package to your root `require` with `@dev` or the matching flag; - or wait for the stable release and keep the constraint as it is. After the stable release ships, remove the flag. Leaving `@beta` in place is harmless for resolution, because stable still satisfies it, but it stops documenting anything useful. ## Pinning a branch to a commit Root `require` entries may also append a commit to a dev version, such as `dev-main#2eb0c09`. Composer's documentation calls this a temporary workaround with severe limits: the solver never sees the reference, the package's own metadata is read from the branch's current state, and a dist install may ignore the pin. Use a tagged release instead as soon as one exists. ## What this does not cover How the selected versions are frozen into `composer.lock`, and how `update` differs from `install`, belong to the lock and install workflow. Stability here only decides which versions are even candidates.