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
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.
phpunit/phpunit example, if the currently installed version is
composer bump updates the
composer.json file to use that version as the lower boundary:
- "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.
composer bump command supports narrowing down the packages that are being bumped to the
require-dev sections with optional flags.
--dev-only: Only bump the
--no-dev-only: Only bump the
For example, the following command only bumps the packages listed under
require-dev section of the
composer bump --dev-only
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.
composer.lock file does not exists, Composer bails out with a success message:
No requirements to update in ./composer.json.
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.
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.* version) and
6.0.* version), by choosing a
symfony/finder version that fulfills both version constraints, such as
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
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.