New composer bump Command in Composer 2.4

Composer 2.4 adds a new command called bump, that increases the requirements listed in the composer.json file with the currently installed version numbers. When the version numbers are bumped in the composer.json file, it effectively prevents Composer from installing a lower version of the required packages.

For example, a composer.json file that requires phpunit/phpunit package with a version constraint 9.4.0 means Composer is allowed to install phpunit/phpunit package versions in the range of >= 9.4.0 >= and < 10.

{
    "require-dev": {
        "phpunit/phpunit": "^9.4"
    }
}

When the composer bump command is executed, it updates the requirement of all packages (unless narrowed down) to the currently installed version, making the current version the lower boundary of the package constraint.

In the phpunit/phpunit example, if the currently installed version is 9.5.20, running composer bump updates the composer.json file to use that version as the lower boundary:

{
    "require": {
-        "phpunit/phpunit": "^9.4"
+        "phpunit/phpunit": "^9.5.20"
    }
}

composer bump command does not update platform requirements such as the PHP version of extension versions.

Narrowing down the package list

The composer bump command supports narrowing down the packages that are being bumped to the require and require-dev sections with optional flags.

• --dev-only: Only bump the require-dev packages.
• --no-dev-only: Only bump the require packages.

For example, the following command only bumps the packages listed under require-dev section of the composer.json file:

composer bump --dev-only

Requires a composer.lock file

The composer bump command requires a composer.lock file that is up to date. This is because the composer bump inspects the composer.lock file to determine the currently installed versions.

If a composer.lock file does not exists, Composer bails out with a success message:

No requirements to update in ./composer.json.

If the composer.lock file is out of date, Composer exits with an error:

The lock file is not up to date with the latest changes in composer.json. Run the appropriate `update` to fix that before you use the `bump` command.

A Word of Caution when Bumping Requirements

Note that when bumping the version constraints, it effectively narrows down the list of possible versions Composer can resolve. When a package is required by multiple immediate or indirect dependencies, narrowing down the version constraints may prevent Composer from correctly resolving the version number.

When libraries require the same package but with different version constraints, bumping one library's lower boundary may prevent it from being used together with another library.

For example, Composer can install symfony/finder library if two libraries require it with version constraints such as 6.0.0 (any 6.* version) and ~6.0.0 (any 6.0.* version), by choosing a symfony/finder version that fulfills both version constraints, such as 6.0.8.

If package A decides to bump the symfony/finder version constraint to 6.1.0, Composer can no longer resolve the version correctly because package B only supports symfony/finder in 6.0 series.

Composer promptly warns on this as well:

Warning: Bumping dependency constraints is not recommended for libraries as it will narrow down your dependencies and may cause problems for your users.
If your package is not a library, you can explicitly specify the "type" by using "composer config type project".
Alternatively you can use --dev-only to only bump dependencies within "require-dev".

As the warning says, it is advised to only update the require-dev section with --dev-only option to to prevent excessively narrowing down the dependency version candidates.