baserCMS 4 から 5 へのアップグレード/移行ルール

このファイルは、baserCMS 4 (CakePHP 2ベース) のコードを baserCMS 5 (CakePHP 5ベース) に移行する際、AIエージェントが遵守すべきルールとパターンを定義します。

推奨: 移行に着手する前に一度 basercms5-claude-workflow-setup（環境セットアップ）を参照し、進め方の環境（権限整理=permissions-audit／その上での Auto mode／設計=superpowers brainstorming／spec・plan の Markdown プレビュー）を整える。提案ベースで、整っていればスキップ。

基本方針

1. フレームワークの差異: baserCMS 4 は CakePHP 2、baserCMS 5 は CakePHP 5 ベースです。CakePHP 2 の記法は基本的に動作しません。CakePHP 5 の記法に完全に書き換えてください。
2. クラスの置換: 廃止されたクラスは、代替クラスまたはPHP標準クラスに置き換えてください。
3. アクセサの利用: プロパティへの直接アクセスは避け、Getter/Setter を使用してください。
4. アップグレードの詳細情報については https://baserproject.github.io/5/ver5_migration を参考にする。
5. 【最重要・横断対応の原則】1画面の修正で見つけた不具合のうち、同じ原因がプラグイン/サイト全体に散在するものは、その場で“横断的に”一括対応する。1箇所だけ直して次の画面で同じエラーに当たる、を繰り返さない。手順: ①エラーを直したら 同じパターンを grep -rn で全件洗い出す（例: $this->Form->input(、'multiple' => 'checkbox'、単数 get('Sample.Sample...')、searches/、Time->format($x) 第2引数なし 等）→ ②機械的に一意な変換は perl -pi で一括適用 → ③変更ファイルを全て php -l で検証 → ④非自明な箇所だけ個別対応。横断一括できる代表例は basercms-plugin-4-to-5-upgrade スキルの C-0（機械的に一括変換できるパターン） にカタログ化してある（見つけ次第追記する）。新しい横断パターンを見つけたらまず C-0 に追加してから一括実行する。プラグイン内部コード（Controller/Table/Entity/View/Helper/フォーム/Vue・JS）の具体的な書き換えは同スキルを参照。

標準移行フロー（この順で進める・正本）

移行全体はこのチェックリストの順序で進める。順序依存の罠（★印）が複数あるため、節の並びや思い込みで順番を変えないこと。各工程の詳細は参照先の節に書いてある。