Basercms Theme 4 To 5 Upgrade

baserCMS テーマの 4 → 5 移行パターン集

本スキルの対象はテーマの baserCMS 4 → 5 移行。テーマは templates/layout・templates/element・templates/Blog・templates/Pages・templates/Mail などのテンプレートが主体で、Controller/Table を持たず、少数のフロント表示ロジック用 Helper（src/View/Helper/*.php）を伴う構成を指す。BcAddonMigrator でテーマを5系のテーマプラグインへ変換した後に必要となる手作業の書き換えパターン（TH-系）と、フロント表示エラーのうちテンプレート・テーマ描画系の実例パターン（F-系）を収録する。

本スキルが扱うのは4系テーマコードの検出と変換である。5系テーマの正しい書き方の正本は basercms5-theme-development（プラグイン内部コードは basercms5-plugin-development）であり、変換先の仕様（テーマプラグインの構造・ビュー変数の作法・ヘルパ・アセットとURL・ウィジェット・メールフォーム/ブログテンプレート）に迷ったらそちらを参照する。以下の各節は「4系イディオムの検出（症状・grep パターン）→ 変換の要点 → 正本スキルの該当節」の形で読む。

テーマ変換の全体手順（テーマの zip 化 → BcAddonMigrator での変換 → plugins/ への配置 → 横断5系化 → sites テーブルの theme への適用）は basercms4-to-5-upgrade スキルの該当節（テーマの変換／移行の標準フロー）を参照すること。本スキルはその工程の中から呼ばれ、変換後のテンプレート・Helper を実際に描画が通る状態へ直すための具体策を提供する。

横断対応の原則（1箇所直したら同じパターンを grep -rn で全件洗い出し → 機械的に一意な変換は一括適用 → 変更ファイルを全て php -l で検証）と、C-0（機械一括変換カタログ）・イベントリスナー/Helper の書き換えパターンは basercms-plugin-4-to-5-upgrade スキルを参照。テーマにプラグイン相当の内部コード（Controller/Table/管理画面）が含まれる場合も同スキルを併用する。

テーマ（Theme）固有の移行パターン（T-/C-系との違い）

テーマは Controller/Table を持たない（プラグインと構造が根本的に異なる）ため、basercms-plugin-4-to-5-upgrade スキルの T-（Table/ORM）・C-（Controller/画面）カタログは基本的に適用外。テーマの主体は templates/layout templates/element templates/Blog templates/Pages templates/Mail と、少数のフロント表示ロジック用 src/View/Helper/*.php。F-系（フロント表示エラー）が主対象だが、テーマ特有の"消えたショートカット系ヘルパーメソッド"の当たり方がプラグインと異なるため、以下に固有パターンとしてまとめる（basercms4-to-5-upgrade の「テーマの変換」章から呼ばれる想定）。

TH-1. $this->BcBaser->siteConfig['key'] / ビュー変数 $siteConfig['key'] は5系に存在しない

• 検出: テンプレ・Helper の $siteConfig['key']／$this->BcBaser->siteConfig['key']（grep -rn "siteConfig\[" templates/ src/）。5系では構文エラーにならず未定義変数／未定義プロパティの警告つきで空文字が出力されるだけなので気づきにくい（サイト名・住所等が黙って空になる）。
• 変換: \BaserCore\Utility\BcSiteConfig::get('key')（静的メソッド）へ。キーは4系 site_configs テーブルの name 列と同じ。1箇所で見つけたら grep でテーマ全体（layout・element・Helper）へ横断適用する。
• 静的ユーティリティの5系の作法は basercms5-theme-development §3「ヘルパ」を参照。

TH-2. グローバル関数 fullUrl() は5系に存在しない

• 検出: Call to undefined function fullUrl() で Fatal（4系のグローバル関数）。
• 変換: \BaserCore\Utility\BcUtil::fullUrl($url)（静的メソッド）へ（basercms5-theme-development §3「ヘルパ」参照）。

TH-3. 4系専用 Component をテーマ Helper が直接インスタンス化しているコードは即Fatal — 先に baser-core に同等機能が移植されていないか確認する

4系のテーマ独自 Helper が new XxxComponent(new ComponentCollection()) のように CakePHP2 の Component を直接生成しているコードが、BcAddonMigrator の機械変換後もそのまま残ることがある。Component 基底クラスも ComponentCollection も5系に存在しないため呼び出された瞬間にFatal（F-4「ヘルパーの手動インスタンス化」と同根だが、対象が Component である点が異なる）。

• 対処の順序: いきなり自前で再実装しない。まず grep -rli "<機能キーワード>" vendor/baserproject/ で baser-core／該当コアプラグインに同等のユーティリティが既に移植されていないか確認する。baserCMS5 は主要な4系専用ロジック（Google Geocoding 連携など）を BaserCore\Utility\* や BaserCore\View\Helper\* として先に移植済みのことが多い。
• 実例: テーマの BcGooglemapsHelper::getLocation() が new BcGmapsComponent(new ComponentCollection())（4系 lib/Baser/Controller/Component/BcGmapsComponent.php。中身は Google Geocoding API への XML リクエスト）を呼んでいた。調査の結果、baser-core に BaserCore\Utility\BcGmaps::getLocation($address)（Cake\Http\Client でのHTTPリクエスト化＋Cache によるキャッシュ付き、戻り値 ['latitude'=>..,'longitude'=>..] は4系と同一形）が既に存在した。テーマ側は独自の load()/_getScript() インターフェースは残しつつ、getLocation() の中身だけをこのコアユーティリティへの委譲に差し替えるだけで解決した（自前でのHTTPクライアント実装・XMLパース実装は不要だった）。
• 見落としがちな呼び出し元: Component 呼び出しは Helper 内に隠れているため、要素テンプレート側からは「単なるメソッド呼び出し」にしか見えない。要素テンプレートで実際にそのメソッドへ到達する条件（デフォルト引数のときだけ呼ばれる、等）を先に読み解いてから Helper 側の実装を追う（本例では「緯度経度が明示指定されていないときだけ loadLocation()→getLocation() に到達する」という条件分岐を確認してから着手した）。

TH-4. BcBaserHelper のショートカットメソッドの実在確認は「関数名 grep」だけでは誤判定する（★訂正済みの教訓）

• 検出: 4系 BcBaserHelper にあったフロント用ショートカット（blogPosts($blogName, $num) 等）の呼び出し。5系では PluginBaserHelper 機構（各プラグインの methods() マッピング）経由で __call に委譲されるため、関数定義が存在しないのが正常。grep -rln "function <名前>" が0件なのを根拠に「5系に代替なし」と判断して呼び出しを無効化してはならない（★実際に誤判定した戒め）。
• 変換の要点: 実在確認は「①関数定義 grep → ②methods() マッピング grep」の2段階で行う。②にあれば提供プラグイン有効時にそのまま動く（無効時は MissingHelperException 系ではなく BadMethodCall になるので、プラグイン無効の可能性も疑う）。①②とも無い場合のみ本当に廃止 → クエリビルダで手動再実装し、複数箇所に散在するならテーマの Helper に集約する。
• 委譲機構と2段階確認手順の正本は basercms5-theme-development §3「ヘルパ」、ブログ記事取得の再実装の基本形（getConditionAllowPublish() 等）は同 §7「ブログテンプレート」を参照。
• 重複実装との突合: 独自実装の element と機能重複がありうる。ただし「重複」判定の前にその element が実際に参照されているか（grep -rn "element('<名前>'"）を確認する — 参照ゼロの未接続ファイルなら重複ではなく、4系挙動に忠実な方（元の呼び出し）を復活させるのが正。

TH-5. layout/element から他プラグインの Helper を直接呼ぶコードは「テーマのバグ」と「依存プラグイン未導入」を区別する

テーマの layout やエレメントが $this->Banner->showBanner(...) のように別プラグインが提供する Helper を直接呼んでいることがある。移行作業を フェーズ3.5（棚卸し） → フェーズ4-(b)（テーマ/プラグイン機械変換） → フェーズ4-(a)（マーケット配布の5系プラグイン導入） のように段階分けしている場合、その依存プラグインがまだ導入されていない段階でテーマ側だけ見ると Undefined property: $this->Banner（Helper未ロード）に見えるが、これはテーマのコードの不具合ではなく、依存プラグインのフェーズがまだ来ていないだけのことがある。

• 対処: 台帳では「未着手／移行済」ではなく **「見送り（依存プラグイン未導入・フェーズ4-(a)待ち）」**のように区別して記録し、テーマ単体の完了条件に含めない。該当プラグインの導入フェーズが終わった後で改めて動作確認する。
• 呼び出し元のメソッド名・期待するオプション（['num' => 0] 等）だけは、後で突き合わせられるよう台帳にメモしておく（導入される5系版プラグインでシグネチャが変わっている可能性があるため）。

TH-6. BcSite::findCurrent() ＋ getBaseUrl() . 'theme/<name>/' でテーマ資産URLを組む4系イディオムは即Fatal

• 検出: grep -rn "BcSite::findCurrent\|'theme/'" templates/ src/。4系はサイトエンティティからテーマ名を取り theme/<name>/img/... 形式のURLを組んでいたが、BcSite クラスは5系に存在せず即 Fatal。
• 変換: テーマ資産はプラグイン webroot 配信形式 $this->BcBaser->getUrl('/<テーマ名snake>/img/...') へ（正本: basercms5-theme-development §4「アセットとURL」）。

フロント表示エラーの実例パターン（症状 → 原因 → 修正）

テーマ／プラグインのフロント表示を復旧させる際に頻出する実例。BcAddonMigrator で自動変換した後も残る典型的な不具合。エラーメッセージで検索して該当パターンに当てること。1つ直すと次のエラーが現れる「玉ねぎ剝き」になるため、curl -sk -o /dev/null -w "%{http_code}" <URL> でステータスを見ながら1件ずつ潰す。

F-1. MissingTableClassException: Table class for alias 'Content' could not be found.

• 検出: 4系流の TableRegistry::getTableLocator()->get('Content')（単数形・プラグイン接頭辞なし）。
• 変換: コアテーブルは複数形＋プラグイン接頭辞（BaserCore.Contents/BaserCore.Sites）へ。あわせて find('first', 配列) → クエリビルダ、配列アクセス → エンティティ（$content->id）、where() の条件キーはテーブルエイリアス付きへ。参照名の規約は basercms5-theme-development §3「ヘルパ」を参照。

F-2. 現在のコンテンツ／サイト情報の取得（リクエスト属性の変更）

• 検出: 4系の $this->request->params['Content']['site_id']／params['Site']['device']（廃止）。
• 変換: リクエスト属性 currentContent/currentSite（エンティティ）から ->id ->site_id ->device 等で参照する。取り方の正本は basercms5-theme-development §2「View・ビュー変数の作法」。

F-3. コアプラグインの参照名に Bc 接頭辞（Helper・テーブル・エレメント共通）

• 検出: 4系の参照名のまま（loadHelper('Blog.Blog')・get('Blog.BlogContents')・getElement('Blog...')）。
• 変換: コアプラグインは Bc 接頭辞へ（Blog→BcBlog、Mail→BcMail）。URL配列だけでなくヘルパー読み込み・テーブルエイリアス・エレメントパスすべてが対象。規約の正本は basercms5-theme-development §3「ヘルパ」。

F-4. ヘルパーの手動インスタンス化（new XxxHelper(new BcAppView())）

• 検出: 4系流の new <Xxx>Helper(new BcAppView())（BcAppView 廃止・DIコンテナ未注入で getService() が失敗する）。
• 変換: $this->getView()->loadHelper('Plugin.Helper') でロードする（loadHelper() はインスタンスを返す）。動的ロードの作法は basercms5-theme-development §3「ヘルパ」を参照。

F-5. League\Container\Exception\NotFoundException: Alias (...ServiceInterface) is not being managed ／ MissingHelperException

フロントが依存するプラグイン（例: BcBlog）が plugins テーブルで status=0（無効） だと、そのプラグインの ServiceProvider がコンテナに登録されず、Helper コンストラクタの getService(XxxServiceInterface::class) で落ちる。

• 判別: SELECT name, status FROM plugins; で対象プラグインの status を確認。
• 修正: v4 で使っていたプラグインを有効化する（正攻法は管理画面のプラグイン管理。データ移行済みでテーブルが揃っているなら UPDATE plugins SET status=1 WHERE name='BcBlog'; でも可）。有効化後は bin/cake cache clear_all。
• 補足: コンテナに無いサービスへ依存しないコードに書き換える手もある（例: テンプレートパス決定はサービスを介さず TableRegistry でブログコンテンツを引いて 'BcBlog...' . DS . 'Blog' . DS . $contentsTemplate . DS . $template を組み立てる）。

F-9. ブログ記事のソート列 posts_date は5系に存在しない

SQLSTATE[42S22]: Unknown column 'BlogPosts.posts_date'。5系の blog_posts の投稿日時カラムは posted。

• 修正: ソート指定を 'sort' => 'posted' にする。カラム名は移行先DBの SHOW COLUMNS FROM blog_posts; で確認するのが確実。

F-11. フロントのヘッダー／メニューが「ログイン時のみ」描画される

ポータル系テーマでは、ヘッダーのナビ・ユーザーメニュー・アプリランチャー等が if(!empty($user)) で囲まれ、未ログインだとロゴ＋サイト名しか出ないことがある。これは仕様。さらにヘッダーは CuAppLauncher CuCustomUser CuTimeCard 等のプラグインに依存するため、それらが無効だと該当ブロックが空になる。

• 確認のコツ: 「ヘッダーが出ない」をコードのバグと早合点しない。まずフロントにログインし、依存プラグインの有効化状況（F-5）を確認する。

F-12. アイキャッチ等の画像404はDBと物理ファイルの不一致のことがある

/files/blog/.../xxxx_eye_catch.jpg の MissingRouteException が大量に出ても、該当画像が移行元（4系）のローカルにも存在しない場合がある（本番サーバーにのみ実体があり、ローカルDBダンプだけ持ってきた等）。移行コードの不具合ではない。

• 判別: 移行元の files/（または app/webroot/files/）に実体があるか確認。古い年月の画像が表示でき新しい年月だけ404なら、ローカルに実ファイルが無いだけ。