Php Migration

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

PHP のバージョンアップで遭遇した非推奨・破壊的変更と修正レシピ集。バージョン別に整理して育てる。CakePHP フレームワーク本体起因の問題は別スキル cakephp-migration を参照。

収録: PHP 8.2 / 8.4 / 8.5。新バージョン対応時は新しい「## PHP X.Y」節を追記する。 注意: PHP 8.5 は 9.0 の直前バージョン。9.0 で非推奨機能はすべて削除されるため、8.5 で出る非推奨警告は早めに潰しておく。

大原則

• 「致命的エラー」と「非推奨警告」を区別する。デバッグモードでは非推奨警告が画面下部に表示され「エラー」に見えるが、logs/debug.log に debug: で出るものは警告（動作は継続）。Fatal/Exception が本当のエラー。
• regression と既存failを切り分ける。git diff HEAD -- <file> で当該ファイルが自分の変更対象か確認。
• 親クラスのシグネチャを変えたら、子クラス・インターフェースも揃える。
• 全非推奨の網羅検出には Rector 等の静的解析が有効。

ユニットテストの実行方法・構文チェック・失敗の切り分けは basercms-unittest スキルを参照。php -l（構文チェック）では暗黙nullable等の非推奨警告も併せて出る。

PHP 8.2

動的プロパティの非推奨

未宣言プロパティへの代入が非推奨。Creation of dynamic property X::$prop is deprecated。

• 対策A（推奨）: クラスにプロパティを宣言する。

  /** @var ThemeFoldersServiceInterface */
  protected $ThemeFoldersService;
  protected $_tempalteTypes = [];

  ※ コンストラクタで $this->Xxx = $this->getService(...) のように代入している箇所が典型。
• 対策B: 多数の子クラスに波及する基底クラス（例: テスト基底 BcTestCase は400超のサブクラスを持つ）には #[\AllowDynamicProperties] を付与。属性は子クラスに継承されるため1箇所で済む。

  #[\AllowDynamicProperties]
  class BcTestCase extends TestCase { ... }

PHP 8.4

1. 暗黙的 nullable 引数の非推奨

型 $x = null は暗黙 nullable で非推奨。明示的に ?型 にする。

// Before
function foo(int $contentId = null, BcAbstractDetector $agent = null)
// After
function foo(?int $contentId = null, ?BcAbstractDetector $agent = null)

• 検出（正規表現）: 先頭に ? が付かず 型 $name = null になっている引数にマッチ。 例: ([A-Za-z_\\][A-Za-z0-9_\\]*)\s+(\$[A-Za-z0-9_]+)\s*=\s*null（直前に ? が無いもの）。
• 親クラスのシグネチャ変更時は子クラス/インターフェースも揃える。
• 警告: Implicitly marking parameter $x as nullable is deprecated, the explicit nullable type must be used instead。

2. fgetcsv() の $escape 非推奨

$escape 引数の省略が非推奨。明示する。

// Before
$head = fgetcsv($fp, 10240);
// After
$head = fgetcsv($fp, 10240, ',', '"', '\\');

• 独自実装（fgets+正規表現でCSVをパースする関数等）は fgetcsv を使っていないので対象外。実際に fgetcsv() を呼んでいる箇所のみ修正する。

3. ReflectionProperty::setValue() の単一引数呼び出し非推奨

静的でないプロパティは対象オブジェクトを渡す。

// Before
$property->setValue($value);
// After
$property->setValue($object, $value);

• 警告: Calling ReflectionProperty::setValue() with a single argument is deprecated。
• テスト用ユーティリティ（リクエスト生成やプライベートプロパティ操作のヘルパ）に潜みやすい。
• 静的プロパティの場合は第1引数に null を渡す: setValue(null, $value)。これは 8.1〜8.5 すべてで有効（8.1 互換を壊さない）。

4. 内部関数の string 引数に null を渡すのが非推奨（実体は 8.1+）

parse_url(null) / version_compare($a, null) / str_replace(..., null) 等、?string でない引数に null を渡すと Passing null to parameter #N ($x) of type string is deprecated。(string) キャストで明示変換する。

// Before → After
parse_url($url);                       →  parse_url((string)$url);
version_compare($current, $required);  →  version_compare((string)$current, (string)$required);

• 8.1 で導入された非推奨だが、移行作業（特に 8.4/8.5 への更新）で大量に顕在化するため本書にも収録。
• 実行時に値が null のときだけ出るため静的 grep では拾い切れない。全テストログの Passing null to parameter を集計して発生元を特定する。

PHP 8.5（2025-11-20 リリース）

9.0 直前の最終マイナー。下記の大半は警告で動作は継続するが、9.0 で削除されるため対応する。アプリ/フレームワークに影響しやすい順に記載。※「0.」のみ警告ではなく致命的エラー（破壊的変更）なので最優先。

⚠️ PHP 8.1 互換を維持する間の注意（composer.json は "php": ">=8.1"）。 8.5 の非推奨を「推奨どおりの置き換え先」で直すと、その置き換え先が 8.1 に存在せず 8.1 が Fatal で動かなくなるものがある。下記の ❌ 印は 8.1 を切るまで据え置き（8.5 で警告は出るが許容）にする。8.5 で動かすこと自体は 8.1 を壊さない（警告のみ）。

• ❌ str_increment()（8.3+）→ 8.1 では $s++ のまま
• ❌ http_get_last_response_headers()（8.4+）→ 8.1 では $http_response_header のまま
• ❌ 名前空間付き PDO（Pdo\Mysql::ATTR_* 等, 8.4+）→ 8.1 では PDO::MYSQL_ATTR_* のまま

上記以外（非正規キャスト、null オフセット→''、自動解放関数の削除、バッククォート→shell_exec、case :、__serialize）は 8.1 でも安全に適用できる。

0. 【破壊的変更・致命的】予約クラス名（Array 等）を use で参照すると Fatal

8.5 で Array などが特別なクラス名として予約され、use ...\Array; や class Array が Fatal（警告ではない）になる。テスト収集（オートロード）段階で落ちるとスイート全体が起動不能になるため最優先。

Fatal error: Cannot use BcMail\Test\TestCase\Model\Array as Array because 'Array' is a special class name

• baserCMS 実績: MailMessagesTableTest.php 冒頭に CakePHP2 時代の残骸 use ...\Array; / use ...\ClassRegistry;（いずれも実在しないクラスへのデッド import）が残っており、8.4 までは無害だったが 8.5 で Fatal 化。該当の use 行を削除して解消（参照箇所は markTestIncomplete 済みの未実行コード）。
• 検出: grep -rnE "use [A-Za-z0-9_\\\\]+\\\\(Array|Object|Resource|Enum|Mixed|Never|Void|Null|False|True|Iterable|Numeric)\s*;" --include="*.php"。
• 注意: 致命的なので php -l ではファイル単体で検出可能。だが全テスト前に grep で一掃しておくと、スイートが収集段階で落ちる事故を防げる。

1. 非正規キャスト名の非推奨（影響大）

(boolean) (integer) (double) (binary) が非推奨。正規名に置換する。

// Before → After
(boolean) → (bool)
(integer) → (int)
(double)  → (float)
(binary)  → (string)

• 検出: grep -rnE "\((boolean|integer|double|binary)\)" --include="*.php"。
• 古いコードに残りがち。機械的に置換可能。

2. null を配列オフセットに使うのが非推奨

$arr[null] / array_key_exists(null, $arr) 等で null をキーに使うのが非推奨（暗黙に "" 変換されていた）。明示的に空文字 "" を使う。

// Before
$arr[null] = $v;  array_key_exists(null, $arr);
// After
$arr[''] = $v;    array_key_exists('', $arr);

• 変数がキーになる箇所（$arr[$key] で $key が null になりうる）に注意。
• 静的 grep では検出困難（実行時に値が null のときだけ出る）。全テストを 8.5 で流して grep "null as an array offset" phpunit.log で発生元（on line N of <file>）を集計するのが確実。
• 修正方針: ① 代入/参照のキーを $key ?? ''（従来の暗黙変換と同等。set/get 両方を同じキーに揃えること）、② isset()/参照の手前で $key !== null && ガード、のいずれか。getData('batch') 等の null 返却を ?? '' で受けるのも有効。
• baserCMS 実績（計 308 件）: BcFileUploader（uploadingFiles[$bcUploadId] の set/get を ?? '' で整合）、BcUploadBehavior（oldEntity[$alias][$entity->_bc_upload_id] を ?? ''）、MailMessagesTable（$dists[$mailField->group_valid]）、SearchIndexes/Contents/PermissionsController（getData('batch') ?? ''）、BcTextHelper::arrayValue / BcUtil::decodeContent（$key !== null && isset(...)）。

3. オブジェクトを自動解放するリソース解放関数の非推奨

対象はリソースではなくオブジェクトになっており、GC で自動解放されるため明示的な close/free 呼び出しが非推奨。呼び出しを削除すればよい。

• curl_close() / curl_share_close()（CurlHandle / CurlShareHandle）
• finfo_close()（finfo）
• imagedestroy()（GdImage）← 画像処理ユーティリティで使われがち
• xml_parser_free()（XMLParser）
• 検出: grep -rnE "\b(curl_close|curl_share_close|finfo_close|imagedestroy|xml_parser_free)\s*\(" --include="*.php"。
• baserCMS 実績: Imageresizer.php・BcFileUploader.php の imagedestroy() 4箇所。単純削除でもよいが、ループ内のメモリ即時解放の意図を保つため unset($img) に置換（GdImage はオブジェクトなので参照を外せば GC が解放。>=8.1 で安全）。