baserCMS プラグイン内部コードの 4 → 5 移行パターン集

BcAddonMigrator でプラグインの雛形を5系へ変換した後に必要となる、手作業のコード書き換えパターンを症状別にまとめたもの。サイト全体の移行手順（baserCMS5 のインストール、BcDbMigrator でのデータ移行、テーマ変換、プラグインの変換手順＝ZIP化→bc_addon_migrator→配置、Git/リポジトリ運用）は basercms4-to-5-upgrade スキルを参照。本スキルはそこから呼ばれ、プラグインの Controller / Table / Entity / View / Helper / フォーム / Vue・JS を1画面ずつ通して動かすための具体策を提供する。

本スキルが扱うのは4系イディオムの検出と変換である。5系の正しい書き方の正本は basercms5-plugin-development（テーマは basercms5-theme-development）であり、変換先の仕様（ORM・コントローラ・フォーム・イベント・Vue連携・日付/数値・ルーティング）に迷ったらそちらを参照する。以下の各節は「4系イディオムの検出（症状・grep パターン）→ 変換の要点 → 正本スキルの該当節」の形で読む。

ブログ記事等にカスタムフィールドを後付けする4系プラグインを5系標準の bc-custom-content へ移行する場合は、本スキルではなく basercms5-custom-content-development を参照する（bc-custom-content は既存 blog_posts への後付けフィールド追加には使えず、独立したコンテンツ種別として作り直す設計になるため、通常のプラグイン内部コード変換とは別の専用パターン集が必要）。

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

移行の進め方（最重要・最初にやる順序）

プラグインの 4→5 移行は、画面を1枚ずつ場当たりで直す前に、まず横断で全体を片付けるのが速くて安全。実証済みの推奨順序:

★★[必須ゲート] あるプラグインの5系化に着手したら、コードを1行でも触る前に、まずステップ1の「ファイル状態台帳」を作る。台帳が無いうちは静的監査(2)も構文変換(3)も始めない。 これは飛ばしやすい（監査や Table 変換にすぐ着手したくなる）が、台帳が無いと「どのファイルが未着手/見送りか」を俯瞰できず、進捗の抜け・二重作業・deferred の取りこぼしが起きる。台帳ファイルを作成 → プレビュー（markdown-to-html）→ それから 2 以降に進む。

1. 全ファイルの状態台帳化: src/templates/js/migration を1行1ファイルで 未着手/移行中/移行済/見送り/対象外 管理（種別×状態サマリ付き、生きたドキュメント）。どこが残っているか俯瞰できる。作成後は状態が変わるたびに更新する（例: docs/migration/<plugin>-file-ledger.md）。
2. ★横断コードチェック（静的監査）を最初に: 全5系コードをアクション/メソッド単位で4系正本と突合し、移行済 / deferred / 4系残骸 / 未実装 ＋バグ(深刻度)＋ブラウザ確認ポイントを監査ドキュメント化する。テストを書く前にやることで、残骸/即Fatal/設計判断が要る箇所を地図化でき手戻りが激減する。並列サブエージェントで種別/ドメイン別に分担すると速い（basercms-unittest の横断監査メモ参照）。
3. ★横断「構文だけ5系化」を次に: 監査で出た4系残骸を5系構文へ一括変換（$this->Model->→fetchTable、find('first',配列)→builder、getDataSource→getConnection、Event の bindModel/$event->data 等。下記 C-0/C-A/§8 のカタログを適用）。完了条件は「php -l 全クリーン＋4系API残骸grepゼロ(deferredのTODO除く)＋既存フルスイート回帰ゼロ」。この段では新規テストを書かない。Fatal を一掃して「5系構文として成立」の土台を作る。外部依存(Slack/メール/CSV/Excel/集計)は中身を移さず // TODO baserCMS5移行: か NotImplementedException で deferred 明示。
4. テスト＆ブラウザで意味検証: 構文変換だけでは保証できない entity↔配列・日付marshal・afterSave連鎖・FormProtection・view変数の形・JS連携(C-F2) を、描画する統合テスト＋ブラウザ確認で詰めて 移行済 に上げる。php -l は構文しか見ず描画/JSの死は捕まらないのでこの段が必須。