Basercms4 To 5 Upgrade

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）の具体的な書き換えは同スキルを参照。

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

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

• 0. 実行環境の確認 — Docker利用有無・コンテナ名・PHPバージョン・プロキシ構成をユーザーに確認 → 「前提: 実行環境の確認」節
• 1. 4系の現状調査 — プラグイン一覧（app/Plugin/）・テーマ（theme/）・DB名/プレフィックス・マルチサイト有無・サブモジュール有無（find app/Plugin theme -name .git）・管理プレフィックス（app/Config/core.php の Routing.prefixes）を洗い出す
• 2. 移行対象の確定（棚卸し） — プラグイン・テーマを1つずつ (a)既存5系版利用/(b)4系を変換/(c)廃止 に分類し、表でユーザーの合意を取る → 「プラグイン棚卸し」節
• 3. 移行計画の作成 — 棚卸し結果を反映した計画を作成しユーザー承認（進め方の環境は basercms5-claude-workflow-setup 参照）
• 4. トピックブランチ作成 — 移行作業用ブランチを切る（例 git switch -c basercms5-migration）。v5 配置物の git 取り込み時の注意は「Git / リポジトリ運用」節（G-1〜G-4）
• 5. 4系バックアップ作成 — v4 管理画面「データメンテナンス」で作成 → zip を v5/tmp/ へ。★PHP切替（7.4→8.1）を伴う環境では、v5 インストール＝PHP を上げる【前】に必ず取る（上げた後だと v4 管理が不調になり得る）→ 「データベース移行手順」節 1.
• 6. 5系を /v5/ にインストール — パッケージ取得 → composer → .env → bin/cake install → 実ブラウザでログイン確認 → 「baserCMSの最新版の取得」〜「baserCMSのインストール」節
• 7. BcDbMigrator 導入 → DB変換 — 変換zipの出力まで。★復元はまだしない（工程12まで待つ）→ 「データベース移行手順」節 2.-3.
• 8. BcAddonMigrator 導入 — 「テーマの変換」節 2.
• 9. (a)既存5系版の導入 ＋ (b)テーマ・プラグインの変換・配置 — (b) は zip 化 → bc_addon_migrator → v5/plugins/ 展開。★(a) の導入もここ（復元前）で行う。終盤に回すとそのプラグインのテーブルにデータが復元されない → 「テーマの変換」「プラグインの変換」節
• 10. プラグインを DB で直接有効化 — plugins テーブル INSERT（Migrations を持つものは migrations migrate -p 併走）。★有効化で boot 経路の4系残骸が fatal 化するので、bin/cake version スモークが通るまで最小修正。検証は CLI＋SQL まで（ブラウザ確認はまだしない — 画面は工程15-17の5系化まで出なくて正常）→ 「プラグインの有効化（DB直接・標準）」節
• 11. テーマを DB で直接適用 — sites.theme UPDATE ＋ キャッシュ全消去 → 「テーマの適用（DB直接）」節
• 12. DB復元 — v5 管理画面「データメンテナンス」で変換済み zip をブラウザ復元（復元CLIなし・ユーザー実施）。★必ず工程10-11（有効化・適用）の後。直前に管理画面ログインの生存だけ確認（フロントは見ない）。復元後にテーブル生成・件数を SQL で検証 → 「データベース移行手順」節 4.
• 13. アップロードファイルの移行 — /files → /v5/webroot/files → 「アップロードファイルの移行」節
• 14. 移行台帳（ファイル一覧）の作成 — 対象プラグイン・テーマごとに構成ファイル一覧と状態を記した台帳を docs/superpowers/ に作る（.superpowers/ はSDD内部スクラッチなので置かない）。以降の横断チェック・動作確認の進捗と懸案はすべてここに記録する。状態の語彙は「未着手／修正済み／非該当（理由付き）」を必ず区別する — 横断チェックで grep にヒットしなかったファイルは「未着手」ではなく「非該当（既知パターンhitなし・最終検証は工程17の描画確認）」。集計表の「完了」は「既知パターンの横断適用が完了」の意味であり全ファイル個別検査済みではない、と台帳に明記する（誤解の実例あり）
• 15. テーマの横断チェック → 5系化（下ごしらえまで） — TH-系パターン（siteConfig[]廃止・fullUrl()廃止 等）を grep で全件洗い出して一括対応 → basercms-theme-4-to-5-upgrade スキル（TH-系＋テンプレート・テーマ描画系の F-系）。完了基準は php -l 全通過まで。描画確認はここではしない（工程17の最初にユーザーと行う）。テンプレのビュー変数は事前の全量マッピングをせず、grep で見つかる「4系特有で5系コアが供給しない変数（$siteConfig 等）」だけ先に書き換え、コア供給分は工程17の実描画＋ログ検出に任せる
• 16. プラグインの横断チェック → 5系化（下ごしらえまで） — C-0（機械一括変換カタログ）を先に全プラグインへ適用 → T-/C-系を個別対応。完了基準は php -l 全通過まで。無理な改善（動くものの過剰リファクタ）はせず、気づきは台帳にメモして先へ進む → basercms-plugin-4-to-5-upgrade スキル
• 17. テーマ→プラグインの順に1つずつ動作確認（ユーザー協働） — ★開始前に移行対象プラグインを一旦全部無効化し（UPDATE plugins SET status=0 WHERE name IN (...)＋キャッシュクリア）、まず「テーマのみ有効」の素の状態でフロント描画をユーザーと確認（レイアウト→トップ→一覧→詳細の画面単位。500 は error.log、穴あき描画は grep "Undefined variable" で機械検出し、警告ゼロまで直す）。その後、確認対象プラグインを1つずつ有効化しながら進める。イベントリスナー等で他プラグインの影響を受けやすく、全部有効のままだと不具合の切り分けができないため。対象が他プラグインに依存する場合はその依存プラグインだけを併せて有効化する。プラグインごとに次の順で:
  • a. コントローラ/テンプレート以外（Table/保存/集計）をユニットテストで確認（依存が重いものはスキップ可・台帳にメモ）→ basercms-unittest スキル
  • b. コントローラの統合テストを作成して実行（この時点の失敗は許容して台帳に記録）。★スタンドアロンUT基盤が入っているプラグインでは b をブラウザ確認より先に回すと費用対効果が高い（実証済み）: GET描画テストが「setting.php の snake_case 由来の全管理画面404」や「control() 自動id とインラインJSセレクタの不一致（C-F2）」をブラウザ往復ゼロで検出した。基盤未導入のプラグインまで b のために基盤導入するかは、画面数とロジック量で判断（イベントグルー中心の小型はブラウザ確認で足りる）
  • c. ユーザーにブラウザ動作確認を依頼（URLはリンク付きで提示）→ エラーはスクリーンショット/文言をもらって解決
  • d. b. で失敗していたコントローラテストを解決（緑化）
  • e. 対象の確認が終わったら有効のまま次のプラグインへ（最終的に全対象が有効・全確認済みになる）
• 18. 懸案プラグインの方針決定・対応 — 棚卸しで「要確認」だったもの・台帳の懸案メモを、ユーザーと方針決定（対応/延期/廃止）して消化する
• 19. 最終統合テスト — ユーザーが実ブラウザでフロント・管理・フォーム・ブログを通し確認。問題があれば解決
• 20. Git 取り込み → 完了 — G-1〜G-4 の確認をして v5 をコミット → 「Git / リポジトリ運用」節

前提: 実行環境の確認（最初に必ず行う）

移行の具体作業（パッケージ取得・composer・bin/cake install・DB移行・ツール変換）に入る前に、実行環境を必ずユーザーに確認する。推測・探索（docker inspect 等）で当てにいかない。

1. Docker を利用しているか、コンテナ名は何かを尋ねる（最重要）: このスキルのコマンド例は docker exec <container-name> ... を多用するが、コンテナ名は環境ごとに異なる。「Docker を利用していますか？ 利用している場合はコンテナ名を教えてください」と最初に質問すること。docker ps や docker inspect で当てにいく前に、まずユーザーに聞く（リポジトリ内に compose 定義が無く別リポジトリにある構成も多く、探索は誤判定・遠回りの原因になる）。DB コンテナ名・DBユーザー/パスワード・VIRTUAL_HOST 等も併せて確認する。
2. 既存コンテナの PHP バージョンを確認する（baserCMS 5 は PHP 8.1+ 必須）: baserCMS 4 は php7.4 等で動いていることが多いが、baserCMS 5 は PHP 8.1 以上が必須。v5 を既存コンテナに同居させる場合、そのコンテナの PHP が 8.1 未満（例 baserproject/basercms:php7.4）なら image を php8.1 以上へ上げる必要がある（compose の image タグを変更 → 再起動）。この image 変更は多くの場合 compose 定義側（別リポジトリのこともある）の編集になるため、編集場所を確認し、リポジトリ外ならユーザーに実施を依頼するか明示許可を得てから行う。
   • ★image を上げる前に、必ず「v4 が動作しなくなる可能性」を警告して確認を取る: PHP を 8.1 に上げると、同居している v4 も 8.1 上で動くことになり、v4 が正常に動作しなくなる可能性がある。切替を実行する前に「コンテナを 8.1 に変更しますが、v4 が動作しなくなる場合があります。それでもよいですか？」と明示的に確認し、了承を得てから変更する。事後に v4 の動作確認を回すのではなく、事前に承諾を得る順序にする（v4 はいずれ廃止する前提のため、切替後の v4 動作確認は不要）。
3. v5 は「既存コンテナ・既存マウントの中のサブディレクトリ」として構築する（別コンテナ/別 vhost を新設しない）: v5 フォルダはプロジェクト直下に作り、既存コンテナのマウント越しに /var/www/html/v5 として同じコンテナで配信する。ログインURLが https://<既存ホスト>/v5/baser/admin/... になるのはこのため。並行稼働のために別サービスを増やす過剰設計をしない（v4 はそのまま無停止で残る）。

コミュニケーションと言語 (重要)

全てのコミュニケーションと作成するドキュメントは日本語で行ってください。

具体的には以下の項目は必ず日本語で記述してください：

1. チャットの返答: ユーザーへのメッセージ、状況報告、質問。
2. Task Artifact (task.md): 進捗管理のチェックリスト、タスク名、サマリー。
3. Implementation Plan Artifact: 実装計画の詳細、ゴール、変更内容、検証計画。
4. Walkthrough Artifact: 作業の振り返り、検証結果の報告。

[重要・URLはリンク付きで提示] ユーザーにブラウザでの動作確認を依頼する場合（管理ログインURL・データメンテナンス画面・フロント確認 等）は、URL を必ず Markdown のリンク付き（[https://...](https://...)）で表示する。プレーンテキストのURLで出さない（ユーザーがクリックしてすぐ開けるようにするため）。例: 👉 [https://<project>.localhost/v5/baser/admin/baser-core/users/login](https://<project>.localhost/v5/baser/admin/baser-core/users/login)。

[重要・ユーザーへの質問は毎回 AskUserQuestion（選択式プルダウン）で] 方針確認・A/B選択・作業依頼の完了確認などユーザーの応答を待つ場面では、本文テキストで問いかけるだけでなく必ず AskUserQuestion ツールを使う。プルダウンが出るとユーザーのスマホに通知が届くが、テキストだけの質問は通知されず気づかれない。移行は長丁場でユーザーが席を外すことが多いため、通知の有無が往復のリードタイムを大きく左右する（ユーザー要望・実運用で確立）。選択肢に収まらない場合も「その他」で自由入力できるので、迷ったらプルダウンにする。

baserCMSの最新版の取得

GitHubから clone するコードは、開発版となっており、実際のプロジェクトでは利用しません。 次のURLを利用して、パッケージングされたコードを利用します。 https://basercms.net/packages/download_exec/basercms-x.x.x.zip

取得したコードは、プロジェクト内に、v5 というフォルダを作成し、そこに配置してください。

取得方法（ホストの curl/wget が deny されている場合の回避）: download_exec URL はブラウザ用の生成ダウンロードだが、WebFetch は「ページを Markdown 化して要約する」ツールのため zip 等バイナリを保存できない。ホストの curl/wget がパーミッションで deny されていることも多い。その場合、Docker を使っているなら「コンテナ経由」で取得できる（Bash(docker:*) が許可されていれば、docker exec ... curl は Bash(curl:*) の deny に掛からない）。プロジェクトはコンテナにマウントされているので、コンテナ内で落とせばホスト側にも実体が出る。最新安定版のバージョンは GitHub Releases（baserproject/basercms の latest）で確認する。

# 例: コンテナ内でパッケージを取得（マウント先 /var/www/html にプロジェクトがある想定）
docker exec -w /var/www/html <container> bash -lc \
  'curl -fL -A "Mozilla/5.0" -o basercms-<x.x.x>.zip "https://basercms.net/packages/download_exec/basercms-<x.x.x>.zip"'
# 取得後: file / unzip -l で zip 妥当性を確認 → unzip -q -o basercms-<x.x.x>.zip -d v5/

コンテナ取得が難しい場合のみ、ユーザーにブラウザDLを依頼してパスをもらう。

composer でパッケージのインストール

composer install を実行します。

• パッケージ版の vendor/ は空（.gitkeep のみ）なので composer install は必須。展開直後に test -d vendor が真でも中身は空のことがある（.gitkeep だけでディレクトリが存在するため）。vendor/autoload.php の有無で判定し、無ければ composer install する。

• 4系プラグインが使っていたサードパーティ製パッケージは v5 に明示的に composer require する: 4系 composer.json 由来のライブラリ（例 phpoffice/phpspreadsheet）は v5 の composer.json/vendor に入っていないことがあり、Class "PhpOffice\PhpSpreadsheet\Reader\Xlsx" not found 等になる。4系の composer.json を参照し、PHP バージョン（v5 は 8.1+）に合うバージョンで導入する（例 docker exec -w <v5> <container> composer require "phpoffice/phpspreadsheet:^1.29" → 1.30.x が入る）。実行後 php -r 'class_exists(...)' で解決を確認。

• Excel/PDF 等の雛形アセット（.xlsx 等）は templates/Admin/Excel/... に移行され、4系の View/Excel/admin/... とはパス構成が違う: 生成系コンポーネント（SampleExcel 等）が Plugin::templatePath('Sample') . 'Excel' . DS . 'admin' . DS . ...（4系配置）を組み立てていると File "..." does not exist。templatePath() は末尾スラッシュ付きなので . DS . を足すと // になる点も注意。5系の実配置 Plugin::templatePath('Sample') . 'Admin' . DS . 'Excel' . DS . <controller> . DS . <file>.xlsx に直す（実ファイル位置を find <plugin> -iname "*.xlsx" で確認）。

.env のコピー

v5 フォルダ内の /config/.env.example を /config/.env にコピーします。

HASH_TYPE を sha1 に設定します。

★SECURITY_SALT に v4 の Security.salt と同じ値を必ず設定する（app/Config/core.php の Configure::write('Security.salt', '...') から転記。.env の該当行はコメントアウトされているので外す）。4系のパスワードは sha1(salt.password) なので、salt が一致しないと DB 復元後に v4 ユーザーで一切ログインできなくなる（実際にハマった。.env 内のコメントにも「4系で利用していたセキュリティーソルトを設定する」と明記されている）。

また、nginx-proxy コンテナを利用している場合は、 .env の TRUST_PROXY の値を true に設定します。

baserCMSのインストール

5系用の新しいデータベースを作成し、v5 フォルダ内でインストールコマンドを実行します。

# 引数の並び: <設置URL> <管理者メール> <管理者パスワード> <データベース名>
#   ★第4引数がDB名。--database というオプションは存在せず、付けると `Unknown option `database`` で失敗する
#   ★サブディレクトリ設置では --baseurl も付ける
bin/cake install [設置URL（例：https://localhost/v5/）] [管理者メール] [管理者パスワード] [DB名（例 <既存DB>_v5）] \
  --baseurl [/v5/] --host [DBホスト名] --username [DBユーザー名] --password [DBパスワード]

• データベース名は第4位置引数（--database オプションは無い）。既存のデータベース名にサフィックスとして _v5 を付与したものを作成した上で渡す。
• サブディレクトリ設置では --baseurl /v5/ を付ける。

.htaccess の RewriteBase は多くの場合そのままで動く（5系既定の .htaccess は相対リライトのため、/v5/ サブディレクトリでも無調整で通ることが多い＝実証済み）。/v5/v5 二重化(404) やリダイレクトループが出た場合にのみ webroot/.htaccess の RewriteBase を調整する（まずは下記 SITE_URL とキャッシュ残りを疑う）。

ログインURLは、https://localhost/v5/baser/admin/baser-core/users/login のような形となります。

• [重要・サブディレクトリ設置時の SITE_URL はサブディレクトリ込みにする＋変更後は必ずキャッシュ全消去] サブディレクトリ設置では config/.env の SITE_URL はサブディレクトリを含むフルURL（例 https://localhost/v5/）が正しい。ここをドメインルート（https://localhost/）に変えてはいけない——一見 /v5/v5 二重化が消えるように見えるが、代わりに管理ログインが自分自身へ 302 する無限ループになる（loginUrl とリクエストパスが食い違い、ログインページが「保護対象」と誤判定されるため）。
  • 管理画面が /v5/v5 二重化(404) や リダイレクトループになったときの真因は、多くが「.env（特に SITE_URL）を変更した後のキャッシュ残り」。baserCMS はルート/URLをキャッシュするため、.env を変えたら必ず bin/cake cache clear_all を実行する。SITE_URL を正しい https://host/v5/ に戻し、キャッシュを消せば解消する（実証済み）。
  • [検証はコンテナ内 curl でなく実ブラウザで] nginx-proxy 配下では、コンテナ内から curl https://localhost/... を叩いても X-Forwarded-Proto 等のプロキシヘッダが付かず、実ブラウザと違うリダイレクト挙動を示す（SSL/正規化リダイレクトの判定がズレる）。管理リダイレクトの生死は必ずプロキシ経由の実ブラウザで確認する。コンテナ内 curl の 302/二重化を鵜呑みにして「サブディレクトリの根本バグ」と誤診しない。

データベース移行手順

データベースの移行は、SQLの直接書き換えではなく、専用プラグイン BcDbMigrator を使用したプロセスを推奨・案内してください。 このプラグインは、コマンドは提供しておらず、ブラウザで利用する必要があります。

1. 前提条件:

   • 移行元: baserCMS 4.5.5 以上であること。
   • 移行先: baserCMS 5 が新規インストールされていること。

2. 移行フロー（DB移行は「①バックアップ→②変換」と「③復元」に分かれる。②までは早期に実施できるが、③復元は必要なv5プラグインを導入した後＝プラグイン棚卸し/変換フェーズの後に行う）:

   1. バックアップ (v4): baserCMS 4 管理画面「データメンテナンス」でバックアップを作成し、ダウンロードした zip を /v5/tmp/ に配置してもらう。
      • [重要・PHPバージョンとの順序] v4 バックアップ作成には v4 管理画面が動く PHP が要る。v5 のために先にコンテナを PHP 8.1 へ上げると、サポート外の v4 管理が不調になり得る。バックアップは PHP を上げる前に取るか、既に上げてしまったら一時的に v4 サポート版（例 php7.4）へ戻してバックアップを取り、再度 8.1 へ戻す（v4 と v5 は必要 PHP が違うため同時稼働はできない）。
      • [重要・v4 管理URLは決め打ちしない] 管理ログインが /admin で 404 になるサイトは管理プレフィックスを変更している（app/Config/core.php の Configure::write('Routing.prefixes', ...)。例 cmsadmin → /cmsadmin/users/login、データメンテナンスは /cmsadmin/tools/maintenance）。404 を安易に「PHP切替で壊れた」と誤診しない——まず Routing.prefixes を確認する。
   2. ツール準備 (v5): BcDbMigrator を配置する。取得は composer でも GitHub でも可（旧記載の「composer 不可」「plugins/ 必須」は誤り＝composer 取得可・vendor 配下でも baserCMS は認識する）:
      • (a) composer: packagist に baserproject/bc-db-migrator が公開されており composer require baserproject/bc-db-migrator:^5.2 で取得できる。ただしこのパッケージの composer.json に autoload 定義が無いため、cakephp plugin-installer が Unable to get primary namespace で config/plugins.php への自動登録に失敗する（＝ダウンロード自体は成功）。確実に使うなら、取得済みファイルを plugins/BcDbMigrator にコピーして下記の DB 有効化を行う（composer からは composer remove して composer.json をクリーンに保つとよい）。
      • (b) GitHub: git clone --branch 5.2.0 https://github.com/baserproject/BcDbMigrator.git plugins/BcDbMigrator（clone 後 .git を除去してサブモジュール化を回避）。※Auto mode では外部リポジトリ取得が分類器にブロックされることがあるので、ユーザーに取得元を提示して承認を得る。 有効化は2通り:
      • (推奨・低摩擦) DB レコードで有効化: BcDbMigrator はインストールスクリプト（マイグレーション）を持たないため、plugins テーブルに1行 INSERT すれば有効化できる（name='BcDbMigrator', title='BcDbMigrator', version='5.2.0', status=1, db_init=1, priority=<末尾+1>, created/modified=NOW()）。ブラウザ操作不要。有効化後 bin/cake にコマンドが出る。
      • (代替) 管理画面のプラグイン管理からインストール。※cake plugin load／config/plugins.php 直接編集は不可（ルーティング不整合でクラッシュ要因）。
   3. 変換実行（CLI 対応・5.2.0 以降）: BcDbMigrator 5.2.0 で CLI 実行に対応した（旧版はブラウザ専用）。docker exec <container> bash -lc 'cd v5 && bin/cake bc_db_migrator tmp/<v4バックアップ>.zip' を実行すると、変換済み zip が v5/tmp/baserbackup_<v5version>_<日時>.zip に出力される（アップロード/ダウンロードの往復が不要。エラー時もアシスタントが反復できる）。変換は一時接続（bcOldDbMigrator/bcNewDbMigrator・接頭辞付き一時テーブル）で行われライブ DB は変更しない（出力は zip のみ）。
      • [重要・baser-core 5.2.5 との非互換パッチ] BcDbMigrator 5.2.0 の変換は旧スキーマPHPを extends \BaserCore\Database\Schema\BcSchema（FQN）に置換するが、baser-core 5.2.5 の BcDatabaseService::isValidSchemaFile() は AST で extends が短縮名 BcSchema の完全一致であることを要求するため、無効なスキーマファイル: BcSchema を継承し、drop/create メソッドをオーバーライドしてはいけません で全滅する（CLI/ブラウザ共通の Component 経路）。対処: plugins/BcDbMigrator/src/Controller/Component/BcDbMigratorComponent.php の _createTableBySchema() 内、extends CakeSchema を FQN でなく短縮名に置換し use 文を足す:

        $contents = preg_replace('/extends CakeSchema/', 'extends BcSchema', $contents);
        $contents = str_replace('<?php', "<?php\nuse BaserCore\\Database\\Schema\\BcSchema;", $contents);

        （本家 BcDbMigrator 未対応のためのローカルパッチ。根本原因は baser-core 側＝isValidSchemaFile() が短縮名の完全一致のみ許可し FQN を弾く点。これを FQN も受理するよう緩和する修正を baserproject/basercms へ PR #4438（5.3.x 宛）で提出済み。マージ・リリースまでは本ローカルパッチ（BcDbMigrator 側で短縮名に置換）が必要。5.3 以降ではパッチ不要になる見込み。）
   4. 復元 (v5): baserCMS 5 管理画面「データメンテナンス」で変換後 zip を復元（復元CLIは無くブラウザ専用）。この工程はプラグイン棚卸し/変換の後に行う（下記「プラグイン」注意点）。
      • 復元は zip の中身基準で動く（実装確認済み）: UtilitiesService::_loadBackup() は zip 内の全 *Schema.php を drop→create し全 CSV を投入するだけで、plugins テーブルの有効/無効は参照しない。したがって、変換済み zip にスキーマ＋CSV が入っているテーブルは、該当プラグインが無効でも取り込まれる（unzip -l で <Table>Schema.php の同梱を確認しておく）。
      • ★復元は plugins テーブル自体も zip の内容（=v4 のプラグイン一覧・全行 status=0）で置き換える（実測）: 復元前に行った有効化レコード（コアの BcBlog/BcMail 等を含む）は全部消えて無効化される。復元後に必ず再有効化する: コア標準6つ UPDATE plugins SET status=1 WHERE name IN ('BcBlog','BcMail','BcUploader','BcSearchIndex','BcThemeConfig','BcWidgetArea') ＋移行対象のうち確認済みのもの（動作確認工程中なら移行対象は 0 のままでよい）。BcDbMigrator/BcAddonMigrator の行も消えるので、引き続き使うなら再 INSERT。実施後 bin/cake cache clear_all。
      • ★sites テーブルも同様に上書きされ、テーマ適用が外れる（実測）: 復元後は全サイト theme='BcThemeSample' に戻る（BcDbMigrator 変換の既定値。マルチサイトの各行も v4 から復元される）。フロントを開くと MissingLayoutException（探索パスに自作テーマが無い）で気づく。復元後にテーマを再適用: UPDATE sites SET theme='<CamelCaseTheme>' WHERE id=<対象サイト>＋キャッシュクリア。＝**「復元後の再設定3点セット: plugins 再有効化・sites.theme 再適用・cache clear_all」**として覚える。
      • ★手動導入したツールプラグイン（BcDbMigrator / BcAddonMigrator 等）も plugins テーブルごと消える（復元は v4 由来の plugins で上書きするため。実測: 復元後に bc_addon_migrator コマンドが Unknown command になる）。ツールを再度使う場合は plugins テーブルへ再 INSERT（＋cache clear）してから実行する。
      • ★マルチサイトは復元後に site_id の整合を必ず検証する（実測・不整合あり）: 復元データはテーブルごとに site_id の変換が食い違うことがある — contents.site_id は「v4 の id +1」（5系標準・メイン=1）に変換される一方、sites.id は AUTO_INCREMENT で 2〜 に詰め直され、プラグイン系テーブル（search_indexes 等）の site_id は v4 のまま無変換。結果、サブサイトの contents が存在しない site_id を指し、サブサイトURL（/blog/ 等）が全部 404 になる。検証SQL: SELECT site_id, COUNT(*) FROM contents GROUP BY site_id と SELECT id, alias FROM sites を突き合わせる。修正は「5系標準＝contents の付番（v4 +1）」に他を合わせる: sites.id と各テーブルの site_id を降順に UPDATE（衝突回避）し、ALTER TABLE sites AUTO_INCREMENT=<最大+1>。site_id カラムを持つテーブルは information_schema.COLUMNS で洗い出す。再復元すると不整合も再発するので、統一SQLを控えておき復元のたびに再実行する。
      • 復元前に管理画面が 500 になる場合、(b)変換組プラグインの無効化で回避してよい: (b)組は boot/描画経路の4系残骸（Event リスナーの viewVars 参照等）で管理画面を壊しがち。上記のとおり復元は無効でもテーブルを取り込むので、UPDATE plugins SET status=0 WHERE name IN (...)＋キャッシュクリアで管理画面を復旧させてから復元してよい（どのみち動作確認工程では一旦全無効化する）。

3. 注意点:

   • ★予約語カラム対応（復元前に必ず設定）: config/install.php の Datasources.default に 'quoteIdentifiers' => true を復元前に必ず入れる。4系サイトはメールフォーム項目由来の check・message 等の予約語カラムをほぼ確実に持っており、未設定だと復元が SQLSTATE[42000] 1064 Syntax error ... near 'check' で途中失敗する。「必要になる場合がある」ではなく既定で設定してよい（quote されて困ることはない）。
   • ★復元の途中失敗は「users が空」を招く（復旧手順）: 復元は zip 内スキーマの drop→create を先に行うため、途中で失敗すると users=0 のままになりログイン不能になる（MySQL は DDL がロールバックされない）。復旧は再インストールが確実:
     1. mv config/install.php config/install.php.bak ＋ .env の INSTALL_MODE="true"（install.php が残っていると「インストール済み」扱いで bootstrap が空DBを参照して落ちる）
     2. DB を DROP→CREATE し bin/cake install <URL> <メール> <パス> <DB名> --baseurl /v5/ --host <DBホスト> --username <ユーザー> --password <パス>
     3. INSTALL_MODE を false に戻し、再生成された install.php に quoteIdentifiers を再設定、プラグインの plugins INSERT・migrations migrate -p・sites.theme を再適用
     4. ブラウザ復元をやり直す。復元中はログアウトしないよう依頼しておく
   • 復元直前・直後のログインの注意: 再インストールやDB作り直しの後は、ブラウザに古い CSRF クッキーが残っていて Missing or invalid CSRF cookie になる → ログインページを再読み込みしてからログインしてもらう。復元成功後は users が v4 のものに置き換わるため、以後のログインは v4 と同じ管理者ID/パスワードになる（事前にユーザーへ伝えておく）。
   • プラグイン（復元との順序）: 標準フローでは変換（早期）→ プラグイン棚卸し/導入・有効化 → 復元の順とする。なお実装上、復元自体は zip の中身基準で動きテーブル取り込みにプラグインの有効/無効は影響しない（上記「復元は zip の中身基準で動く」参照）。順序を守る実利は「復元前に有効化まで済ませておくことで、復元後すぐ管理画面でプラグインデータを確認できる」「zip にスキーマが無いテーブル（Migrations でしか作られないもの）を先に作れる」こと。
   • メモリ: バックアップ作成時にメモリーオーバーエラーとなる可能性があります。その際、ユーザーに php.iniの memory_limit の変更を促してください。
   • 小数点: decimal(8,2) などを利用しているテーブルの場合、正常に移行できないので、別途、SQLで定義、インポートする必要があります。

アップロードファイルの移行

/files ディレクトリを /v5/webroot/files に移動してください。

• v4 並行稼働中は「移動」でなく「コピー」にする（v4 側の表示を壊さない）。数GBあるためコンテナ内で cp -a するのが速い。
• ★ネスト罠: v5/webroot/files は復元やプラグイン有効化の時点で既に一部生成されている（theme_configs/ uploads/ やブログのディレクトリ骨格など）。そのため cp -a /path/files /v5/webroot/files とすると files/files/ にネストしてコピーされる。既存ディレクトリへのマージは cp -a /path/files/. /v5/webroot/files/（末尾 /.）で中身をコピーする。ネストしてしまったら cp -a .../files/files/. .../files/ && find .../files/files -delete で解消。
• 未移行時の症状: アイキャッチ等のアップロード系URLは、実体ファイルが無いとヘルパのフォールバックで**ルート相対 /files/...（サブディレクトリ無し）**が出力され、v5 ページから v4 の files を誤参照する（v5 の error.log に MissingRouteException: /files/... が並ぶ）。files 移行後は /v5/files/... が正しく生成される。この工程は「プラグイン有効化→描画確認」より前に済ませること。
• 移行後の検証: 描画HTMLの src を curl | grep -o 'src="[^"]*files[^"]*"' で抜き、静的配信の 200 を確認する。ローカル環境では DB は最新なのに files が古い（本番から持ってきた時期のズレ）ことがあり、その 404 は移行起因ではない — v4 側の同パスにも実体が無いことで切り分ける。

テーマの変換

テーマの変換には、BcAddonMigrator プラグインを使用します。

1. 準備: baserCMS 4 のテーマフォルダを ZIP 圧縮します。
   • 重要: 圧縮する際は、テーマディレクトリの親ディレクトリ（theme/）を含めず、テーマディレクトリ自体がルートになるように圧縮する必要があります。
   • 手順例:

     # 1. テーマ名を特定 (データベースの site_configs テーブルを確認)
     # 例: SELECT value FROM site_configs WHERE name = 'theme';
     # 結果: my-custom-theme
     
     # 2. テーマディレクトリ名をキャメルケースに変更
     # 例: my-custom-theme -> MyCustomTheme
     THEME_NAME="my-custom-theme"  # 実際のテーマ名に置き換える
     THEME_CAMEL="MyCustomTheme"    # キャメルケースに変換
     
     # ★【最重要・データ破壊注意】変換後の名前が「大文字小文字だけの差」になる場合
     # （例: philosophy → Philosophy）、macOS 等のケースインセンシティブFSでは
     # theme/<camel> が元ディレクトリと同一に解決され、一時コピーの削除で
     # **元テーマ本体を削除してしまう**（実害あり。サブモジュールなら
     # `git submodule update --init theme/<name>` で復旧できる）。
     # 同名ケース差になるテーマは theme/ 配下でなく一時ディレクトリへコピーする:
     #   cp -r "theme/${THEME_NAME}" "/tmp/${THEME_CAMEL}" して /tmp 側で zip する
     cp -r "theme/${THEME_NAME}" "theme/${THEME_CAMEL}"
     
     # 3. ZIP圧縮 (node_modules除外)
     mkdir -p v5/tmp/zip
     cd theme
     zip -r "../v5/tmp/zip/${THEME_CAMEL}.zip" "${THEME_CAMEL}/" -x "*/node_modules/*"
     rm -rf "${THEME_CAMEL}"
     cd ..
     
     # 4. 圧縮後の確認（重要）
     unzip -l "v5/tmp/zip/${THEME_CAMEL}.zip" | head -n 20
     # ルートが MyCustomTheme/ であること、theme/ ディレクトリが含まれていないことを確認

2. ツール: baserCMS 5 に BcAddonMigrator をインストール・有効化します（GitHubより取得）。 * 注意: BcAddonMigrator は GitHub から取得し、plugins/BcAddonMigrator に配置する。有効化は plugins テーブルへの直接 INSERT で可（インストールマイグレーションを持たないため。実証済み。「プラグインの有効化（DB直接・標準）」節の手順2）。cake plugin load／config/plugins.php 直接編集は不可。
3. 変換（コマンドライン）: bc_addon_migrator コマンドを使用してテーマを変換します。

   # Docker環境の場合
   THEME_CAMEL="MyCustomTheme"  # 実際のキャメルケーステーマ名に置き換える
   docker exec <container-name> bash -c "cd v5 && bin/cake bc_addon_migrator --type=theme tmp/zip/${THEME_CAMEL}.zip"
   
   # 出力: v5/tmp/${THEME_CAMEL}_5.2.0.zip

4. 配置: 変換されたZIPファイルを v5/plugins/ に展開します。

   THEME_CAMEL="MyCustomTheme"  # 実際のキャメルケーステーマ名に置き換える
   cd v5/tmp && unzip -q -o "${THEME_CAMEL}_5.2.0.zip" -d ../plugins/

   • 注意: 変換は完全ではありません。必ずコード全体を目視確認し、手動修正を行ってください。
5. 手動修正:
   • モデルデータ: 配列アクセス ($post['BlogPost']['name']) をエンティティプロパティ ($post->name) に変更。
   • URL: 配列形式のリンクに 'plugin' キーを追加し、コントローラー名をアッパーキャメルケースに変更（例: 'controller' => 'search_indexes' → 'controller' => 'SearchIndexes'）。
   • フォーム: $this->BcForm->create('Model') を $this->BcForm->create($entity) または null に変更。input() を control() に変更。
   • エレメント: パス指定を PluginName.element_name 形式に変更。