Is “content-hash” a mandatory part of composer.lock?

Purpose of the content hash

As you can see in Composer\Package\Locker::getContentHash(), the content hash takes into account the following fields of composer.json:

$relevantKeys = array(
    'name',
    'version',
    'require',
    'require-dev',
    'conflict',
    'replace',
    'provide',
    'minimum-stability',
    'prefer-stable',
    'repositories',
    'extra',
);

The only reason for the content hash to change is a change of one of the values of the corresponding properties in composer.json.

Composer uses the content hash to determine whether relevant fields in composer.json are in sync with composer.lock. You can run

$ composer validate

to find out if they are in sync.

If composer.json and composer.lock are not in sync, a message similar to this will be shown

The lock file is not up to date with the latest changes in composer.json, it is recommended that you run composer update.

For reference, see https://getcomposer.org/doc/03-cli.md#validate:

You should always run the validate command before you commit your composer.json file, and before you tag a release. It will check if your composer.json is valid.

Resolving conflicts in composer.lock

If you have trouble resolving conflicts in composer.lock, maybe this helps:

Step 1: Accept upstream changes

Usually, you will probably attempt to rebase a branch on top of the upstream changes. When already in conflict, use your IDE, or run

$ git checkout --theirs composer.lock

to accept the upstream changes to composer.lock. Since this is a generated file, you really don’t want to resolve conflicts in it.

Step 2: Re-apply changes to composer.json and composer.lock

As pointed out earlier, there are a range of the relevant keys in composer.json. Some of them can be modified by corresponding commands, others cannot.

For example, if one of the changes is a newly added or removed package, run

$ composer require foo/bar:^1.2.3

or

$ composer remove foo/bar

to apply the changes.

If the changes cannot be applied by running a command, manually modify composer.json, then run

$ composer update --lock

This will update the content hash.

For reference, see https://getcomposer.org/doc/03-cli.md#update:

–lock: Only updates the lock file hash to suppress warning about the lock file being out of date.