公式ドキュメントを参考にしてコードを書いたら、deprecated の Notice が大量に出た。
これは、
- ドキュメントには、それを知りうるように書いてあったか
- いつからこうなっていたか
- どうすればよいのか
を追いかけた記録である。
ことの始まり
ドキュメントを見ながら CakePHP 4.4 を利用したコードを書き始めた。
if (!$query->isEmpty()) {
// ～～
}
しかし、デバッグのためにログを見たところ deprecated の Notice が大量に出ていてエラーが埋もれていた。これではデバッグどころではない。
このコードはドキュメントを見ながら書いたはずなのに、一体どういうことなんだろうか。
ドキュメントを確認
私が見たはずの、データ取得のドキュメントを再度確認してみた。
日本語のドキュメント（4.x）
Document 4.x (ja) [2023-10-22 閲覧]
// クエリーをチェックします
$query->isEmpty();
// 結果をチェックします
$results = $query->all();
$results->isEmpty();
確かに私はこれを見て書いた。では英語のドキュメントはどうなっているだろう。
英語のドキュメント（4.x）
Document 4.x (en) [2023-10-22 閲覧]
// Check a query.
$query->isEmpty();
// Check results
$results = $query->all();
$results->isEmpty();
こちらも $query->isEmpty(); を使うように書いてある。
CakePHP 4.4 で deprecated が出るということは、最近出たという CakePHP 5.x ではこの書き方が廃止されているかもしれない。そのドキュメントがどうなっているか確認してみる。
日本語ドキュメント（5.x）
Document 5.x (ja) [2023-10-22 閲覧]
// クエリーをチェックします
$query->isEmpty();
// 結果をチェックします
$results = $query->all();
$results->isEmpty();
同じだ。では英語ではどうだろう？
英語ドキュメント（5.x）
Document 5.x (ja) [2023-10-22 閲覧]
// Check results
$results = $query->all();
$results->isEmpty();
英語はでは変わっている。
データ取得のドキュメントのまとめ [2023-10-22 時点]
| 日本語ドキュメント | 英語ドキュメント | |
|---|---|---|
| 4.x | 古い | 古い |
| 5.x | 古い | 新しい |
移行ガイドの記述
CakePHP 4.3 移行ガイド には、このような記述がある。
クエリをプロキシするすべての ResultSetInterface メソッド（
CollectionInterfaceを含む） （これらは強制的に結果を取得し、その結果に対してプロキシされたメソッドを呼び出します）は非推奨になりました。 非推奨な使い方の例として、$query->combine('id', 'title');があります。 これを$query->all()->combine('id', 'title');に変更する必要があります。
このドキュメントを読んで isEmpty() が該当するかどうか判るには、isEmpty() が Query オブジェクトのメソッドではなく ResultSet のメソッドであることを知っていなければならない。私がこれ（4.3 にこの記述があること）を見つけられたのはそのことを知っていたからではなく、ソースの変更を追いかけたところ 4.3.0RC という文字があったからである。
いつからこうなった？
- [2015-03-23] CakePHP 3.0 リリース
- 3.x のドキュメントでも $query から isEmpty() を呼ぶコードがあるので、3.0 からこのように書けるようだ。
- [2021-07-07] deprecated の Notice を出すソースの変更はここで行われた
- [2021-10-24] CakePHP 4.3 リリース
- deprecated の Notice が出るようになる
- ドキュメントの移行ガイドには記述がある
- ドキュメントのサンプルは古いまま
- [2023-01-25] CakePHP 5.x のドキュメント（英語のみ）が更新された。
- [2023-09-10] CakePHP 5.0.0 リリース
- 本当に削除されたのかどうかは、試していないのでわからない。
- ドキュメントのサンプルは、英語は改訂されているが日本語のは古いまま
どうなっていてほしいか
CakePHP 3.x のドキュメントにはこのような書き方をしているところがある。
// コントローラーやテーブルのメソッド内で
// Prior to 3.6 use TableRegistry::get('Articles')
$articles = TableRegistry::getTableLocator()->get('Articles');
$query = $articles->find('ownedBy', ['user' => $userEntity]);
このようにどちらの書き方も紹介されていれば、メジャーバージョン内で変化があっても理解することができる。
Pull Request を出してみた
自分で直せるのが OSS だし、言い出しっぺの法則というものがあるし、ただ文句をたれるだけでは生産性がない。
そこで、マージされるかわからないが Pull Request を出してみた。
Pull Request がマージされた（2023/10/28 追記）
これでわかりやすくなったことだろう。