basercms4-to-5-upgrade

name	basercms4-to-5-upgrade
description	baserCMS 4 (CakePHP 2ベース) のコード・サイトを baserCMS 5 (CakePHP 5ベース) へアップグレード／移行する際に AIエージェントが遵守すべきルールとパターン集。「baserCMS 4 から 5 へ移行」「4系を5系にアップグレード」「BcDbMigrator でデータ移行」「BcAddonMigrator でテーマ／プラグイン変換」「CakePHP 2 → CakePHP 5 への書き換え」「admin_ プレフィックスメソッドの Controller/Admin への移動」「config/setting.php・config.php の return 配列化」「init.php 廃止と PluginClass 作成」「migration_snapshot 生成」「site_configs theme → sites theme」「移行の標準フロー／工程の順序」「プラグインを DB で直接有効化」「テーマを DB で直接適用」「request->data／query／params の getter 化」「File/Folder クラス廃止」「ClassRegistry → TableRegistry」「FrozenTime → DateTime」「FixtureManager → FixtureFactory」等、4→5 アップグレード作業全般で参照する。プラグイン内部コード（Controller/Table/Entity/View/Helper/フォーム/Vue・JS）の具体的な書き換えパターンは basercms-plugin-4-to-5-upgrade、テーマ（templates 中心）の移行は basercms-theme-4-to-5-upgrade、5.2→5.3 のプラグイン移行は basercms-plugin-5x-update、CakePHP本体起因は cakephp-migration、PHP本体起因は php-migration、テスト実行は basercms-unittest スキルを参照。移行先である5系での正しい書き方（開発の正本）は basercms5-plugin-development / basercms5-theme-development を参照。
license	MIT

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直接・標準）」節

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

移行の具体作業（パッケージ取得・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()）。ブラウザ操作不要。有効化後 にコマンドが出る。

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

/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' → ）。

プラグインの変換

プラグインの変換にも BcAddonMigrator プラグインを使用します。 ただし、GitHubのリポジトリ等で既に baserCMS 5 に対応したバージョンが公開されている場合があります。その場合は、変換作業を行わず、そちらを利用してください。

プラグイン棚卸し（変換前に必ず・プラグインごとに方針決定）

プラグインを一括変換にかける前に、プラグインを1つずつ棚卸しし、「4系を変換する」か「既存の5系版を使う」かをユーザーと確認して決める。いきなり全プラグインを BcAddonMigrator にかけない（既に公式/作者が5系版を出しているものを二重にメンテすることになる）。

• 調査: 各プラグインについて、①baserCMS 公式の 5系標準搭載（baser-core/bc-* に統合済みか）②作者/配布元の GitHub・baserマーケットに 5系対応版があるか③外部SaaS連携等で5系版が別提供か、を確認する。判断材料が乏しいものは「要確認」として残す。
• 分類してユーザーに提示（例）:
  • (a) 既存5系版を使う: 公式統合済み・作者が5系版を公開しているもの（例: エディタ系・OGP系など外部配布物）。→ 変換対象から除外し、composer/管理画面で5系版を導入。
  • (b) 4系を変換して移行: 独自実装で5系版が無いもの（自社プラグイン等）。→ BcAddonMigrator で変換 → 内部コードを5系化。
  • (c) 廃止/不要: 5系で標準機能に吸収された・もう使わない機能。→ 移行しない。
• 表で合意を取る: 「プラグイン名／4系での役割／5系版の有無・入手先／方針(a/b/c)」の一覧を作り、ユーザーに (a)(b)(c) を確認してから次工程へ進む。テーマについても同様に棚卸しする。
• この棚卸し結果を移行計画（plan/spec）に反映し、(b) のものだけを変換フェーズの対象にする。
• ★(a)のうち非公開配布・要購入・要ライセンス等でエージェントが自力入手できないものは、棚卸し表で明示的に区別し「誰が・いつ入手/設置するか」までユーザーと合意して記録する。単に「(a) 既存5系版を使う」と分類しただけでは、入手・設置の担当と期限が宙に浮き、実行フェーズで着手されないまま進行しがちである（実例: 棚卸しドキュメントに記載していたエディタ系プラグインの5系版導入が、非公開配布でユーザー側の入手が必要だったにもかかわらず後続フェーズで実施されず、フロントの表示崩れとして移行完了後に顕在化した。原因は棚卸しを一度作って終わりにし、実行状況を追跡していなかったこと）。
• ★棚卸しは作って終わりにせず、移行完了を宣言する前に棚卸し表と実際の導入状況を突き合わせて検証する。(a)分類の項目は「導入済みか」を個別に確認し、未導入のものが残っていれば移行計画のスコープ外に放置せず、対応時期（今回対応／別タスクとして継続）をユーザーと再確認してから完了とする。

1. 準備: baserCMS 4 のプラグインフォルダを ZIP 圧縮します。
   • 重要: テーマ同様、親ディレクトリ（app/Plugin/）を含めず、プラグインディレクトリ自体がルートになるように圧縮する必要があります。
   • 手順例（全プラグインを一括で圧縮）:

     # app/Plugin/ に移動して全プラグインを圧縮（node_modules除外）
     mkdir -p v5/tmp/zip
     cd app/Plugin
     for d in */; do 
         name=${d%/}
         zip -q -r "../../v5/tmp/zip/${name}.zip" "$name" -x "*/node_modules/*"
     done
     cd ../..
     

2. 変換（コマンドライン）: bc_addon_migrator コマンドを使用して全プラグインを一括変換します。

   # Docker環境の場合
   docker exec <container-name> bash -c "cd v5 && for zip in tmp/zip/*.zip; do bin/cake bc_addon_migrator \"\$zip\"; done"
   
   # 出力: v5/tmp/<PluginName>_5.2.0.zip (各プラグインごと)
   

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

   cd v5/tmp && for zip in *_5.2.0.zip; do unzip -q -o "$zip" -d ../plugins/; done && cd ../..
   

4. クリーンアップ: 不要なZIPファイルを削除します。

   rm -rf v5/tmp/zip v5/tmp/*_5.2.0.zip
   

   • ★baserbackup_*.zip（DB変換済みバックアップ）は削除しない。v5/tmp/ には BcDbMigrator の出力 zip も同居しているため、ワイルドカードは変換中間 zip（<PluginName>_<version>.zip）だけに掛かるよう対象を限定する。
   • rm -rf が Bash 権限で拒否される環境では find <path> -delete を使う（例: find v5/tmp/zip -delete。ファイル個別は find v5/tmp -maxdepth 1 -name '<Name>_*.zip' -delete）。
   • 注意: 変換は完全ではありません。必ずコード全体を目視確認し、手動修正を行ってください。
   • BcAddonMigrator がやること／やらないこと（実測）:
     • やること: Controller/Model/View の src/ 名前空間化、admin_ メソッドの Controller/Admin 分離、src/<Name>Plugin.php の生成（空クラス class <Name>Plugin extends BcPlugin {}）、config.php/setting.php の return 配列化。
     • やらないこと: config/Schema（4系 CakeSchema）→ config/Migrations への変換（4系 Schema がそのまま残る）、config/init.php の除去（残骸として残る）、内部コードの5系化（ClassRegistry・$this->data 等は残存）。
     • つまり変換直後は「配置と は通るが、Migrations 無し・4系残骸あり」が正常な状態。復元運用なら有効化に支障はない（「プラグインの有効化（DB直接・標準）」節参照）。Migrations 生成・残骸掃除・内部5系化は横断チェック工程（フロー15-17）で行う。

プラグインの有効化（DB直接・標準）

配置した移行対象プラグインの有効化は、plugins テーブルへの直接 INSERT を標準とする。ブラウザ往復ゼロでエージェントが自走でき、検証も SQL で完結する（管理画面有効化は代替手段として注記参照）。 ★テーマは plugins テーブルに登録しない（新規インストール直後の plugins にデフォルトテーマ BcFront の行が無いことから実証済み）。テーマの適用は次節「テーマの適用（DB直接）」の sites.theme UPDATE のみでよい。

1. 有効化前チェック（プラグインごと）: ls v5/plugins/<Name>/config/Migrations で Migrations の有無を確認する。
   • (a)既存5系版のプラグインは通常 Migrations を持つ（有効化時にテーブル作成が必要）。
   • (b)BcAddonMigrator 変換組は通常 Migrations を持たない（4系 config/Schema が残っているだけ）。復元 zip にスキーマ＋データが含まれるかを unzip -l v5/tmp/baserbackup_*.zip | grep -iE "<table名>" で確認し、含まれていれば復元がテーブルを供給するので Migrations 生成は不要（クリーンインストール運用にする場合のみ bake migration_snapshot で生成）。
2. plugins テーブルへ INSERT（全プラグイン共通）:

   INSERT INTO plugins (name, title, version, status, db_init, priority, created, modified)
   VALUES ('<Name>', '<Name>', '<version>', 1, 1,
           (SELECT p FROM (SELECT COALESCE(MAX(priority),0)+1 AS p FROM plugins) tmp), NOW(), NOW());
   

   複数件あるときは priority を連番でずらす。
3. Migrations を持つプラグインはマイグレーションを併走（INSERT だけではテーブルが作られない）:

   docker exec <container> bash -lc 'cd /var/www/html/v5 && bin/cake migrations migrate -p <Name>'
   

4. キャッシュ全消去: bin/cake cache clear_all（プラグインロード構成が変わるため）。
5. 検証は CLI 起動スモーク＋SQL まで（この段階でブラウザ確認はしない）: SELECT name, status FROM plugins で status=1、Migrations 実行組は SHOW TABLES でテーブル生成を確認し、bin/cake version が fatal なくバージョン番号を返すこと（=有効プラグイン全部の bootstrap が通ること）を確認する。フロント/管理画面のブラウザ確認はまだ求めない — 内部コードが4系のままなので画面は出なくて正常。ブラウザ確認は動作確認工程（標準フロー17）以降。管理画面が必要になるのは復元（フロー12）だけなので、その直前に管理画面ログインだけ生存確認すればよい。

★有効化で顕在化する boot 経路の4系残骸（先に潰す）

(b)変換組を有効化すると、画面以前にアプリ起動（bootstrap）で fatal になる4系残骸が動き出す（php -l では捕まらない実行時エラー）。有効化後の bin/cake version スモークで1つずつ顕在化するので、最小修正（TODO マーカー付き）だけしてフロー15-16（本格5系化）へ先送りする。実測した典型パターン:

場所	症状	最小修正
src/Event/*EventListener.php	Class "<NS>\Event\ClassRegistry" not found（BcEvent が有効プラグインのリスナーを bootstrap で instantiate するため、コンストラクタ内の4系APIが即死）	ClassRegistry::isKeySet/getObject 分岐を削除し TableRegistry::getTableLocator()->get() 一本化
config/setting.php	Class "CakeLog" not found ／ Configure::load が配列を得られない	CakeLog::config() 等の実行文を除去（ログ設定は Phase 4 で Plugin::bootstrap へ）。$config['X'] = [...] は return ['X' => [...]] へ
config/setting.php 内の4系定数	Undefined constant "CACHE_DATA_PATH" 等	5系の定数（TMP・CACHE 等）へ置換
config/routes.php	Router::connect 静的呼び出し・CakeRequest・BcSite::findByUrl で fatal	ファイル全体を return; で無効化＋旧定義をコメント保存（Phase 4 で RouteBuilder 形式に書き換え）

スモークが通る（bin/cake version がバージョンを返す）までこの表の要領で潰す。 ★CLI スモークの限界に注意: bin/cake version は Web リクエストと bootstrap 経路が一部異なり、BcEvent のリスナー生成起因の fatal（例: コンストラクタでの Table 即時取得→MissingTableClassException）をすり抜けることがある（実測）。CLI スモーク通過＝Web も無事、ではない。Web 側の最終確認は管理画面の GET 統合テスト（工程17-b）か実ブラウザで行う。リスナーのコンストラクタでは Table を即時取得せず遅延取得にするのが安全。

• 直 INSERT が安全な根拠: BcAddonMigrator が生成する Plugin クラスは空（class XxxPlugin extends BcPlugin {}）で独自 install 処理を持たないため、管理画面有効化との差は「マイグレーション自動実行の有無」だけ。それは手順3で補える。独自の install() をオーバーライドしているプラグインだけは中身を確認し、必要なら管理画面から有効化する。
• （代替）管理画面のプラグイン管理から有効化するとマイグレーションが自動実行される。ユーザーがブラウザ操作できる状況ならこちらでもよい。
• config/plugins.php の直接編集は不可（既出の注意どおりクラッシュ要因）。
• この工程で全対象を有効化するのは「復元でテーブル・データを取り込むため」（フロー12の前提）。復元が済んだら、動作確認工程（フロー17）の開始時に移行対象を一旦全部無効化し、確認対象＋その依存だけを1つずつ有効化しながら進める（イベント干渉の切り分けのため）。無効化/再有効化は UPDATE plugins SET status=0（/1） WHERE name='<Name>'＋bin/cake cache clear_all で行える（テーブルとデータは残るので安全）。

テーマの適用（DB直接）

5系ではテーマは site_configs ではなく sites テーブルの theme カラムで管理される。適用も DB 直接更新を標準とする。

-- サイトごとに適用（マルチサイトは site 単位で theme を持つ。全サイト同一テーマなら WHERE 句なし）
UPDATE sites SET theme = '<CamelCaseTheme>' WHERE id = 1;

• 適用後は必ず bin/cake cache clear_all（テーマ解決がキャッシュされるため）。
• 検証は実ブラウザでフロントを開き、テーマのテンプレートが使われていること（500 でないこと）を確認。テーマ側テンプレートの4系残骸でエラーになる場合は、この時点では台帳に記録して工程15（テーマ横断チェック）で対応する。

プラグイン内部コードの変換（別スキル）

BcAddonMigrator で変換した後の プラグイン内部コードの具体的な書き換え（Controller の $this->Model→fetchTable、Table の initialize() アソシエーション宣言・find() クエリビルダ化、Entity/getControlSource、View/Helper、検索フォーム・編集フォームの BcAdminForm/control() 化、Time::format の ICU、Number::format/Text::truncate の null 対応、Vue・JS の $.bcUtil.adminBaseUrl 化と webpack 再ビルド、フロント表示エラーの症状別対処 等）は、専用スキル basercms-plugin-4-to-5-upgrade にカタログ化している。プラグインの画面を1枚ずつ通して動かす段階では、そちらを参照すること（C-0 機械一括変換カタログ／T- Table・ORM／C- Controller・画面／F- フロント表示エラーのうちプラグイン文脈分）。テーマ（templates 中心）の移行パターン（TH-系＋テンプレート・テーマ描画系の F-系）は basercms-theme-4-to-5-upgrade スキルに分割している。変換先＝5系の正しい書き方の正本は basercms5-plugin-development（プラグイン）／ basercms5-theme-development（テーマ）を参照。

移行の進め方（ユニットテスト先行 → ドメイン単位で画面結合）

BcAddonMigrator 変換後のプラグイン内部コードを手作業で5系化する工程は、次のワークフローで進めると速くて安全（実証済み）。目的は、任意の baserCMS4系プロジェクトを最小の手間で5系へ移行できる状態を作ること。

なぜこの順序か: 移行では「画面表示は動くのに、保存・集計・出力ロジックが静かに壊れている」ケースが多い（按分計算・集計の戻り値形状・絞り込み条件・本番に無い列など、目視では正しさを判断できない）。一方でユーザーの最大の手間は画面テストのリロード反復。テストはAIが自律実行でき人手が要らない。よって テストで正しさを固めてから、画面結合をまとめて1回 が最も手間が少ない。

1. フェーズ1: ロジックをテスト駆動で移行（人手ほぼ不要）。対象ドメイン（見積／請求／売上／集計 等）の Table/保存/集計/出力ロジックを、責務を整理しつつ TDD で5系化。Factory＋ユニットテストで「4系と同値」を数値で固定（RED→GREEN・回帰自動担保）。→ テスト基盤は basercms-unittest、変換パターンは basercms-plugin-4-to-5-upgrade（T-/C-/F-）。
2. フェーズ2: 薄いグルー層。コントローラは「受け→Table/Service呼び→set」の薄さに保ち、ロジックはテスト済みの Table/Service へ寄せる。画面で確認すべき面積（テスト不能なグルー）を最小化。
3. フェーズ3: ドメイン単位で画面結合を1回。ロジックが全部緑になってから、1回の画面セッションでテンプレート/JS・Vue/遷移/CSV・Excel/通知の結合を確認。事前に「どの画面で何を操作し何が期待結果か」のチェックリストを用意し、ユーザーは順に1往復するだけにする（リロードを「メソッドごと」でなく「ドメインごと」に集約）。
4. フェーズ4: スキルへフィードバック。一段落ごとに、再利用可能な知見を該当スキル（プラグイン内部コード→basercms-plugin-4-to-5-upgrade、テスト→basercms-unittest、サイト手順→本スキル、5系共通ルール→basercms5-development、5系の実装パターン→basercms5-plugin-development / basercms5-theme-development）へ反映。症状→原因→修正・コード断片・戒めまで残す。

結合タイミングはドメインごと（見積を固める→見積画面を1回確認→次は請求…）。問題を新鮮なうちに発見でき手戻りが小さい。

長丁場セッションの運用（コンテキスト肥大対策・こまめに /compact）

4→5移行は1セッションが普通のタスクより長くなりやすい（環境構築→DB移行→棚卸し→変換→ドメインごとの5系化…と工程が多い）。セッションが長引くと、コンテキスト肥大でアシスタントのツール呼び出しが壊れ始めることがある（症状: <invoke>/<parameter> の名前空間プレフィックス欠落や、先頭に無関係な語＝例「court」が紛れ込んでコマンド／ツール呼び出しが失敗する。環境やシェルの不具合ではなく、アシスタント側の出力フォーマット崩れ）。

• 対処: この種の失敗が数回続いたら、粘って再試行せず早めに /compact でコンテキストを圧縮してから続行する（要点は要約に引き継がれるので作業は継続できる）。工程の区切り（各フェーズ完了時など）でも予防的に /compact してよい。
• 予防: 大きな中間成果物（計画・台帳・調査ログ）は会話に溜め込まず、spec/plan ファイルや scratchpad に書き出しておくと、compact 後も参照が楽で肥大も抑えられる。

Git / リポジトリ運用（移行コードのバージョン管理）

4系プラグインを BcAddonMigrator で変換し v5 に配置した後、git に取り込む際の定番のハマりどころ。G-2〜G-4 はどのプロジェクトでも該当。G-1 は 4系で git サブモジュールを使っていたプロジェクト限定（多くのプロジェクトはサブモジュール未使用なので該当しない）。

G-1.【サブモジュールを利用している場合のみ】変換済みプラグインに残る4系サブモジュールの .git（gitlink）を除去

※ この項目は、4系でプラグインを git サブモジュール（.gitmodules に登録）として管理していたプロジェクトのみ対象。サブモジュールを使っていなければ .git は付いてこないので無関係（find v5 -name .git が 0 件なら該当なし）。

4系で git サブモジュールだったプラグイン（app/Plugin/<X>）をコピーすると、.git（gitlink ファイル）も付いてくる。これは gitdir: ../../../.git/modules/app/Plugin/<X>（=4系本体のサブモジュール格納庫）を指したままで、「同じ git モジュールに2つの作業ツリーが紐づく」「変換済み5系コードが4系HEADと全差分」等の矛盾を起こす。

• 対処: find v5 -name .git -type f -delete で v5 配下の gitlink ファイルを削除（実コード・.gitignore・4系の実サブモジュール/.git/modules/.gitmodules には触れない＝安全）。これで変換済みプラグインは「普通のディレクトリ」になる。

G-2. baserCMS5 標準 .gitignore は /plugins/* を無視する → 自作プラグインを negation

v5 同梱 .gitignore は /plugins/* を無視し、コア/サンプル（!/plugins/baser-core, !/plugins/bc-*, !/plugins/BcColumn 等）だけ negation で追跡する設計。そのままでは変換済みの自作プラグインが追跡対象外になる。

• 対処: 自作プラグインを !/plugins/Sample のように negation 追記（git check-ignore v5/plugins/Sample が空＝追跡可、で確認）。/plugins/*/vendor・/plugins/*/node_modules・/plugins/*/composer.lock・schema-dump-default.lock は無視のまま。

G-3. アップロード実体 webroot/files/* は git に含めない

v5 標準 .gitignore は /webroot/files/* を無視する（正しい既定）。4系から移行したアップロード（本プロジェクトは 1.7GB / 1万超ファイル）を git に入れると repo 肥大化・clone 遅延・GitHub 制限で push 不可になり得る。除外のままにし、実体は別途バックアップ／再コピーで運用する（!/webroot/files/.gitkeep で空ディレクトリ保持）。git add -n v5 | wc -l 等で巨大物の混入を事前確認するとよい。

G-4. v5 のネスト/取り込み

git add v5 時、ネストした v5/.gitignore は親リポジトリでもそのまま効く（秘匿 config/.env・app_local.php・vendor・tmp・logs は自動除外される）。git add -n（dry-run）でステージ予定を必ず検証してからコミットする。プラグインを将来「再利用可能な独立リポジトリ」にしたい場合も、まずは親に通常ファイルで取り込み、安定後に git subtree split で切り出す段階移行が扱いやすい。

注意事項

• コードを提案する際は、必ず CakePHP 5.0 の公式ドキュメントおよび baserCMS 5 のソースコード（vendor/baserproject/ 以下）との整合性を確認してください。
• 「たぶん動く」CakePHP 2 のコードを残さないでください。
• [重要] ターミナルコマンドを実行する際は、バックグラウンド実行（& を末尾につける、またはツールの WaitMsBeforeAsync を短く設定して放置するなど）を行わないでください。処理が滞留し、後続の操作を受け付けなくなる可能性があります。必ず同期的に完了させてください。