Basercms Plugin 5x Update

baserCMS プラグイン バージョン移行ガイド（5.2 → 5.3）

baserCMS プラグインを 5.2系 から 5.3系へ移行する際に遭遇した baserCMS 固有の問題と修正レシピ集。バージョン別に整理して育てる。

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

収録: 5.2 → 5.3。5.3系は PHP 8.5 / CakePHP 5.2.x ベース（執筆時点で開発中）。 役割分担:

• PHP 本体起因（暗黙nullable・動的プロパティ・非正規キャスト・setAccessible・null オフセット等）→ php-migration スキル
• CakePHP 本体／関連パッケージ起因（AbstractMigration→BaseMigration・イベント戻り値・PluginCollection・TreeBehavior・ResultSet・order()/group() 等）→ cakephp-migration スキル
• ユニットテストの実行・集計・切り分け手順 → basercms-unittest スキル
• 本書は上記に当てはまらない baserCMS 固有 + プラグインのテスト基盤 に絞る。

大原則

• 「致命的エラー」と「非推奨警告」を区別する。logs/debug.log の debug: や logs/error.log の error: で …は非推奨です と出るものは警告（動作継続）。Fatal / Exception が本当のエラー。
• テスト大量失敗は根本原因単位で分類する。数百件でも原因は十数種。例外メッセージを集計して systemic な原因（vendor 混在・プラグイン未ロード・フィクスチャ不正）から潰す。
• 依存の更新は composer require を使い、composer update で依存全体を動かさない（cakephp-migration 大原則と同じ）。

5.2 → 5.3 の変更

0. 依存バージョンの更新（composer.json）

プラグインの require-dev（または require）の baser-core を 5.3 系に上げる。

"require-dev": {
    "baserproject/baser-core": "5.3.x"
}

• 上げた後は composer update baserproject/baser-core --with-dependencies（プラグインの vendor を持つ場合）で 5.3 系 + CakePHP 5.2.x を取り込む。
• PHP 要件は 8.1 互換を維持するなら "php": ">=8.1" のまま（8.5 の非推奨対応は php-migration の ❌ 印=据え置き方針に従う）。

テスト基盤（standalone プラグイン test harness）

自前 vendor/ と tests/TestApp/ を持つ「単体実行型」のプラグインを 5.3 で動かすと、ここが最も詰まる。コアプラグイン（親ディレクトリのアプリ経由でテスト）の場合はアプリ側 tests/bootstrap.php が同等の処理をしているので、本節はアプリ側を参照する。

T-1. CakePHP の二重ロード（vendor 混在）で validateUnique(): Argument #2 ($options) not passed

composer test が ルートの phpunit（../../vendor/bin/phpunit）を起動する一方、プラグインの tests/bootstrap.php が ROOT/vendor/autoload.php（=プラグイン自前 vendor）を読み込むと、2つの異なる CakePHP バージョンが同時にロードされる。Composer のオートローダは register(prepend=true) で後勝ちになるため、起動時に読まれたクラス（例 Cake\ORM\Table 5.0系）と実行時に初めて読まれるクラス（例 Cake\Validation\Validator 5.2系）が混在し、validateUnique() 等でシグネチャ不一致の ArgumentCountError が出る。

• 判別: スタックトレースに …/vendor/cakephp/…（ルート）と …/plugins/<plugin>/vendor/cakephp/…（自前）の 両方が現れる。
• 修正（standalone）: テストはプラグイン自前の vendor/bin/phpunit で実行する。bootstrap が読む ROOT/vendor と phpunit bin の autoload が同一 vendor になり、CakePHP が単一バージョンに揃う。

  // plugins/<plugin>/composer.json
  "scripts": { "test": ["Composer\\Config::disableProcessTimeout", "vendor/bin/phpunit --colors=always"] }

  実行（Docker 経由・basercms-unittest 参照）: docker compose exec <container> sh -c "cd /var/www/html/plugins/<plugin> && vendor/bin/phpunit"

T-2. plugins.php の null → []（CakePHP 5.2 の PluginCollection::create が array 必須）

tests/TestApp/config/plugins.php の値が null だと、BaseApplication::bootstrap() → PluginCollection::addFromConfig() → create($name, null) で TypeError: …create(): Argument #2 ($config) must be of type array, null given になる（5.1 までは許容）。

// Before → After
return ['BaserCore' => null, ...];  →  return ['BaserCore' => []];

• 関連: cakephp-migration 1-4 にも同記述あり。

T-3. プラグインの読み込みは BcApp.testAppPluginsToLoad を使う（plugins.php は BaserCore のみ）

baser-core 5.2+ の BcTestCase::loadTestAppPlugins() は Configure::read('BcApp.testAppPluginsToLoad') を読み、未 bootstrap が無くなるまでスナップショット単位で（ガード付きで）各プラグインを bootstrap する。

• plugins.php には BaserCore のみを記載し、コンテンツ系プラグイン（BcBlog / BcCustomContent / BcSearchIndex 等）と対象プラグイン自身は testAppPluginsToLoad に列挙する。本体アプリ（config/plugins.php は BaserCore + 基盤のみ、tests/bootstrap.php で Plugin::loaded() から testAppPluginsToLoad を生成）と同方式。

  // plugins/<plugin>/tests/bootstrap.php（Migrator の後など）
  Configure::write('BcApp.testAppPluginsToLoad', [
      'BcMcp',            // 対象プラグイン自身
      'BcSearchIndex', 'BcBlog', 'BcCustomContent', // 依存コンテンツプラグイン
  ]);

T-4. 統合テストで Plugin named 'X' is already loaded（二重ロード例外）

T-3 と必ずセットで守る。プラグインを plugins.php と testAppPluginsToLoad の両方に書くと、統合テストがリクエスト毎に生成する per-request app が plugins.php を再び addFromConfig し、既に読み込み済みのプラグインを再 add して CakeException: Plugin named 'X' is already loaded（CakePHP 5.2、cakephp-migration 2-7）になる。500 → さらに後述 T-6 でマスクされ「原因不明の 500」に見える。

• 修正: BaserCore は plugins.php、その他は testAppPluginsToLoad に分離して重複させない。

T-5. 同梱サブプラグインのクラスが not found（例 Class "BcCcFile\Utility\BcCcFileUtil" not found）

BcCcFile は bc-custom-content に同梱されたサブプラグイン（vendor/baserproject/bc-custom-content/plugins/BcCcFile/）で、BcCustomContentPlugin::bootstrap() → loadPlugin() が App.paths.plugins を追加し BcUtil::includePluginClass() で動的に PSR-4 登録する。composer の autoload には現れないため、親プラグインが bootstrap されないとクラス解決できない。

• 修正: 親プラグイン（BcCustomContent）を T-3 の testAppPluginsToLoad に入れて bootstrap させる。サブプラグインの namespace を composer.json に手書き登録する必要はない。