Cakephp Migration

CakePHP バージョン移行ガイド（baserCMS）

CakePHP のアップグレードで遭遇した破壊的変更・非推奨と修正レシピ集。バージョン別に整理して育てる。PHP 本体起因（暗黙nullable・動的プロパティ等）は別スキル php-migration を参照。

収録: 5.0 → 5.1、5.1 → 5.2。バージョンの帰属は移行作業時の実観測ベース（厳密な導入版と差異がありうる）。新バージョン対応時は新しい「## X.Y → X.Z の変更」節を追記する。

大原則（全バージョン共通）

• アップグレードは composer require を使う。composer update は使わない（依存全体が動くのを避ける）。 例: composer require cakephp/cakephp:"5.2.*" --update-with-dependencies
• 「致命的エラー」と「非推奨警告」を区別する。デバッグモードでは非推奨警告が画面下部に表示され「エラー」に見えるが、logs/debug.log の debug: は警告（動作継続）。logs/error.log や Fatal/Exception が本当のエラー。
• テスト大量失敗時は根本原因単位で分類する。数百件の失敗でも原因は十数種。フルログから例外を集計して systemic な原因を先に潰す（集計コマンド・切り分け手順は basercms-unittest スキル参照）。
• regression と既存/環境failを切り分ける。git diff HEAD -- <file> で自分の変更対象か確認。未変更ファイルかつ fixture/プラグインロード依存（Plugin::isLoaded('X') が false／DIコンテナ未登録／英語↔日本語メッセージ不一致）なら移行起因ではなく環境要因。vendor が既に新版に入れ替わっているため単純な git stash ではクリーンな baseline は作れない。

ユニットテストの実行方法・失敗の集計と切り分け手順は basercms-unittest スキルを参照。

5.0 → 5.1 の変更

5.1 では E_USER_DEPRECATED 系の非推奨が増える。Error.errorLevel で抑制可能だが、本対応として潰す。

1-1. Query::order() / group() の非推奨

order()→orderBy()、group()→groupBy()（SelectQuery::group() も）。

// Before
$query->order(['Contents.id'])->group('site_id');
// After
$query->orderBy(['Contents.id'])->groupBy('site_id');

1-2. find('all', $options)（options 配列）の非推奨（Since 5.0.0）

options 配列渡しが非推奨。名前付き引数 or スプレッドにする。

// Before
$this->Table->find('all', ['limit' => $n, 'conditions' => $c]);
// After（いずれか）
$query = $this->Table->find()->where($c); if ($n) $query->limit($n);
$this->Table->find('all', ...$options);   // $options のキーが finder の名前付き引数に一致する場合
$this->Table->find('all', conditions: $c, order: $o);

• 既に ...$options / conditions: 等になっているものは対象外（誤検出注意）。
• 警告: Calling 'findAll' finder with options array is deprecated. Use named arguments instead.

1-3. ページネーション結果が PaginatedResultSet に

paginate() の戻り値が PaginatedInterface（PaginatedResultSet）になり、isEmpty() 等の ResultSet メソッドを直接持たない。先に ->items() を呼ぶ。

// Before（テンプレート等）
if (!$sites->isEmpty()) { ... }
// After
if (!$sites->items()->isEmpty()) { ... }

1-4. 翻訳キャッシュ設定のリネーム

_cake_core_ → _cake_translations_。config/app.php・config/bootstrap.php・BcUtil 等の参照を更新。

• config/plugins.php で 'BaserCore' => null のような値は 'BaserCore' => [] にする。

5.1 → 5.2 の変更

5.2 は「これまでサイレントに上書き/許容していた操作を例外化」する変更が多い。

2-1. イベントリスナーの戻り値返却が非推奨（5.3 でエラー化）

リスナーから値を return せず、$event->setResult() / $event->stopPropagation() を使う。戻り型は : void にできる。

// Before
public function beforeSave(EventInterface $event) { return false; }
// After
public function beforeSave(EventInterface $event): void { $event->setResult(false); }

• Table/Marshaller コールバックの戻り値は元々無視されるので単に return を削除すればよい（beforeMarshal は ArrayObject $data を参照で書き換える。返り値は使われない）。
• コントローラ beforeFilter の定番修正:

  // Before
  $response = parent::beforeFilter($event);
  if ($response) return $response;
  ...
  return $this->redirect(...);
  // After
  parent::beforeFilter($event);
  if ($event->getResult()) return;
  ...
  $event->setResult($this->redirect(...));
  return;

• クロージャ内の return（SEO等）は対象外（誤検出注意）。

2-2. AssociationCollection::add() が重複エイリアスで例外化

5.1までサイレント上書き → 5.2は Association alias 'X' is already set. を throw。 initialize() で定義済みの関連を、別メソッド/Service/Controller で hasMany/belongsTo 等で再設定すると発生（finder 差し替え等）。

// 再設定の前に既存を削除してガードする
if ($table->associations()->has('CustomLinks')) {
    $table->associations()->remove('CustomLinks');
}
$table->hasMany('CustomLinks')->setFinder('all')->...;

• inline hasMany('X') は、ガード済みの専用メソッド（例: setHasManyLinksByAll()）に集約すると安全。
• 検出: grep -rnE "\->(hasMany|belongsTo|belongsToMany|hasOne)\(" --include="*.php" で Service/Controller 内の関連設定を洗う（Table の initialize 以外は要注意）。

2-3. 重複バリデーションルール名で例外化

同一フィールドに同名ルールを2回 add すると A validation rule with the name 'X' already exists。5.1は上書き。

• 同名ブロックが重複していれば統合（後勝ちの意図を保つ）。例: alias に対する複数の検証定義をまとめる、minLength を一度だけ追加する等。
• コールバックの名前付き引数 $context の衝突に注意（独自メソッドの第2引数を $context にしない）。
• 注意: テストが「同じ validator に同メソッドを2回呼んで上書きを確認」している場合はテスト側の事情で、本番フロー（1フィールド1回）では起きない＝アプリ修正対象外のことがある。

2-4. ResultSet の型・clone 不可

• Query::all() の戻り値が Cake\ORM\ResultSet（旧 ResultSetDecorator）。型宣言は ResultSetInterface か iterable に緩める。
• ResultSet は clone 不可・イテレータ共有。clone $resultSet や、ライブな ResultSet への二重イテレートで要素が消える。->toArray() で早期に materialize してから使う（フォームの項目が消える等の不具合の原因）。
• ヘルパ/サービスの引数型は ResultSetInterface/iterable にし、is_array($x) ? $x : $x->toArray() で吸収。

2-5. 配列条件の null 値が例外化

where(['field' => null]) は Expression 'field' has invalid 'null' value. ... operator (IS, IS NOT) is missing. を throw。null安全な IS 演算子を使う。

// Before
$conditions = ['Contents.entity_id' => $entityId];   // $entityId が null だと例外
// After
$conditions = ['Contents.entity_id IS' => $entityId]; // 非nullなら =、nullなら IS NULL

2-6. エンティティの文字列キャスト非推奨

テンプレ等で (string)$entity 相当（HTML 属性へ直挿し等）が非推奨。json_encode($entity) を使う。

$this->BcBaser->js('...', false, ['data-current' => json_encode($content)]);

2-7. PluginCollection::add() が既ロードで例外化

Plugin named 'X' is already loaded。addPlugin の前にガードする。

if (!$application->getPlugins()->has($name)) {
    $application->addPlugin($name);
}

• テーマ（coreFrontTheme 等）と $themes 配列で同名が二重追加されるケースに注意（addTheme()）。
• Migrations / Authentication / CakephpFixtureFactories 等の追加箇所も同様にガードする。

2-8. FormProtection の _Token not found（postLink + 独自JS）

baserCMS は postLink のフォームを独自JS（plugins/bc-admin-third/src/js/admin/common/lib/jquery.bcToken.js）で再構成して送信する。 CakePHP 5.2 で postLink の onclick が document.{form}.submit() → document.{form}.requestSubmit()（CSP対応）に変わり、抽出用正規表現が一致せず _Token が送られなくなる。

// jquery.bcToken.js: 両対応にする
var regex = /document\.(post_.+?)\.(?:request)?[Ss]ubmit\(\)/;

• 修正後は管理テーマの JS を再ビルド: cd plugins/bc-admin-third && npm run build（bcToken は common/startup バンドルに含まれる。webpack が src/**/*.js を自動エントリー化）。
• 個別アクションを unlockedActions で除外するより、この正規表現修正の方が全 postLink を一括で直せる（CSRF保護も維持）。プラグイン無効化・テーマ切替/コピー/削除・キャッシュクリア等が一斉に復旧する。

2-9. PluginCollection の live イテレーション中の変更で後続プラグインの bootstrap がスキップ

5.2 の BaseApplication::pluginBootstrap() は PluginCollection::with('bootstrap') の live なジェネレータを走査する。あるプラグインの bootstrap() がイテレーション中に addPlugin()/remove()（テーマ追加・DebugKit 削除等）でコレクションを変更すると、直後に並ぶプラグインの bootstrap() がスキップされ、setting.php 等が読み込まれず Configure::read('BcXxx....') が null になる。

• 本番では問題のプラグイン（baserCMS では BaserCorePlugin）がコンテンツプラグインを「後から」追加するため直後に要素が無く顕在化しないが、テストで事前ロード（appPluginsToLoad 相当）すると顕在化する。
• 修正: live イテレーションをやめ、未 bootstrap が無くなるまでスナップショット単位で bootstrap する（テスト基盤 BcTestCase::setUp 等）。

  $booted = [];
  do {
      $pending = [];
      foreach ($app->getPlugins() as $plugin) {
          if ($plugin->isEnabled('bootstrap') && !in_array($plugin->getName(), $booted, true)) $pending[] = $plugin;
      }
      foreach ($pending as $plugin) { $booted[] = $plugin->getName(); $plugin->bootstrap($app); }
  } while ($pending);

2-10. View::_checkFilePath() の第2引数がプラグイン名に（.. を含むテンプレートで MissingPluginException）

5.2 で View::_checkFilePath(string $file, ?string $plugin) が第2引数 $plugin を _paths($plugin) に渡すようになった。_getTemplateFileName()/_getLayoutFileName() をオーバーライドしてファイルシステムパスを第2引数に渡していると、パスをプラグイン名と誤解して .. を含むテンプレート（render('../element/...') 等）が 500 になる。

• 修正: 第2引数にはパスではなくプラグイン名を渡す。_checkFilePath($path . $name, $path) → _checkFilePath($path . $name, $plugin)。
• .. を含まない通常テンプレートは早期 return のため影響なし（顕在化するのは .. 経由のみ）。

2-11. TreeBehavior: ルートに parent_id=null をセットして保存するとツリー破損

5.2 の TreeBehavior は、ルート（parent_id=0）のエンティティに parent_id=null をセットして保存すると「ルートへの移動」とみなして lft/rght を再計算する。結果ツリーが壊れ、配下の URL 生成等が失敗する。

• 修正: ルート更新時は parent_id をデータに含めない（変更しない）。

  $data = ['id' => $id, 'name' => $name, ...];
  if (!is_null($rootContentId)) $data['parent_id'] = $rootContentId; // ルート(null)では parent_id を触らない

2-12. Table::get() の第2引数も名前付き引数に（配列 options は非推奨）

find() と同様、5.2 で Table::get($id, mixed ...$args) となり options 配列は非推奨。

// Before → After
$table->get($id, ['contain' => ['Users']]);   →  $table->get($id, contain: ['Users']);
// 動的に options を組む場合はスプレッドで名前付き引数展開（PHP 8.1+）
$query->find($finder, array_merge(['prefix' => $prefix], $options));
  → $query->find($finder, ...array_merge(['prefix' => $prefix], $options));

• スプレッド展開は文字列キーの連想配列前提（finder/get の名前付き引数名に一致）。

2-13. Entity::set([...])（配列一括セット）の非推奨

エンティティへの配列一括セットは patchEntity() を使う。

// Before（テスト等）
$entity->set(['field' => $v, ...]);
// After
$table->patchEntity($entity, ['field' => $v, ...]);