composer の「Warning: The lock file is not up to date ～」

composer install で次の警告が表示されたのでなんなのか調べました。

Warning: The lock file is not up to date with the latest changes in composer.json. You may be getting outdated dependencies. Run update to update them.

原因

composer.json ファイルの md5 と、 composer.lock に記録されたハッシュ値が一致していません。

おもいで

次のような理由で composer.json と composer.lock にズレが生じたためでした。

1. あるプロジェクトで開発者全員/プロダクション/ステージングなどの各環境で依存パッケージのバージョンを固定させたいので composer.lock も VCS に含めていました
2. ある日、機能追加のために依存パッケージを composer require で増やしました
3. composer.json を確認すると、依存パッケージが追加された以外にところどころホワイトスペースが元の内容から変更されていました
4. なんか気に入らなかったのでホワイトスペースだけ元に戻して composer.json と composer.lock を commit/push しました
5. composer.json と composer.lock にズレが生じて警告がでるようになりました

ホワイトスペースを少し弄っただけだったのですが、composer.lock には composer.json ファイルの md5 がそのまんま記録されているので、1 バイトでも手を加えると警告が表示されます。

解決

composer update で composer.lock を更新できますが、それだと固定したはずの依存パッケージのバージョンまで更新されます。それはとても困ります。

composer update --lock とすれば composer.lock に記録されたハッシュ値だけ更新されます。

$ composer update --lock
Loading composer repositories with package information
Updating dependencies (including require-dev)
Nothing to install or update
Generating autoload files

composer.json を手修正したときは composer update --lock しておくとよさそうです。

おまけ

composer update --help で表示される説明・・・

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

composer.lock のハッシュ値だけ更新されるように読めますが、composer.json の require にパッケージを追加/削除して composer update --lock すると、パッケージによってインストール/アンインストールも一緒にされたりされなかったりしました。

単に composer.json の md5 を計算して composer.lock に書き込むだけにしては異様に時間かかるなーとは思いましたが・・・

恐らく、dev-master のようなブランチに基づくバージョンが指定されたパッケージは composer update --lock だけでインストール/アンインストールまで行なわれている、ような気がします。