- PHP 8.1以降、
htmlspecialchars()やtrim()などの標準関数にnullを渡すと非推奨警告(Deprecated)が発生する(PHP 9.0でTypeErrorへ昇格予定) - 文字列整形・エスケープ・検索系の関数には、Null合体演算子(
$val ?? '')で空文字を渡すのが最も安全で簡潔 explode()やjson_decode()など「空文字を渡すと挙動が変わる関数」は、安易に?? ''せず事前に空判定で分岐させる
1. 発生する症状・やりたいこと(前提条件)
PHP 7.4 / 8.0 から PHP 8.1以降(8.2 / 8.3 / 8.4)へバージョンアップした際、それまで問題なく動いていた画面やバッチ処理で以下のような Deprecated(非推奨)警告が大量に出力されるケースがあります。
- DBのNULL許容カラム(
bioやremarksなど)から取得した値を、そのままhtmlspecialchars()やtrim()、mb_strlen()に渡したとき - フォーム入力(
$_POST/$_GET)やAPIの未指定パラメータ(null)をpreg_match()やexplode()で処理したとき strict_types=1を宣言していないレガシーコードで、標準関数の暗黙的な型変換(null→"")に依存していたとき
Deprecated: htmlspecialchars(): Passing null to parameter #1 ($string) of type string is deprecated in /var/www/app/View.php on line 24
Deprecated: trim(): Passing null to parameter #1 ($string) of type string is deprecated in /var/www/app/ProfileService.php on line 42
2. ❌ やりがちなNGコード vs ⭕ 実務で使える正解コード
エラーが出る原因と、機械的な置換によるバグを防ぎつつ PHP 8.3 / 8.4 以降に完全対応する修正コードを比較します。
<?php
// DBから取得したレコード(NULL許容カラムが null のケース)
$user = ['name' => '山田 太郎', 'bio' => null, 'tags_csv' => null];
// NG 1: null を直接渡すと PHP 8.1+ で Deprecated(strict_types=1 なら TypeError)
$bio = trim($user['bio']);
echo htmlspecialchars($bio, ENT_QUOTES, 'UTF-8');
// NG 2: 警告消しのために無思考で (string) キャストすると [''](1要素)になりバグる
$tags = explode(',', (string)$user['tags_csv']);
echo count($tags); // 0件のつもりが「1」と判定されてしまう!
PHP 8.0までは標準関数に null を渡すと暗黙的に空文字 "" へ変換されていましたが、PHP 8.1以降は非推奨(E_DEPRECATED)となりました。また、explode(',', (string)$user['tags_csv']) のように一律キャストすると、null のときに空配列 [] ではなく [''](空文字1件の配列)が返り、件数判定やループ処理でバグを引き起こします。
<?php
declare(strict_types=1);
// DBから取得したレコード(NULL許容カラムを含む)
$user = [
'name' => '山田 太郎',
'bio' => null,
'tags_csv' => null,
'price' => null,
];
// 1. 文字列整形・エスケープ系:Null合体演算子(?? '')で空文字にフォールバック
$bio = trim($user['bio'] ?? '');
$safeBio = htmlspecialchars($bio, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
// 2. 文字列長・部分一致判定:空文字を渡せば 0 や false が安全に返る
$bioLength = mb_strlen($bio, 'UTF-8'); // 0
// 3. 区切り文字での配列分割:空文字のときは explode() を呼ばず空配列 [] を返す
$rawTags = trim($user['tags_csv'] ?? '');
$tags = ($rawTags === '') ? [] : explode(',', $rawTags);
// 4. 数値フォーマット系:第1引数は float 型のため ?? 0 を渡して float キャスト
$formattedPrice = number_format((float)($user['price'] ?? 0));
var_dump($safeBio, $bioLength, $tags, $formattedPrice);
// 出力: string(0) "", int(0), array(0) {}, string(1) "0"
3. 仕様・使い分けの比較早見表
標準関数に null が渡る可能性がある場合、関数の種類によって「そのまま ?? '' してよいもの」と「条件分岐が必要なもの」が分かれます。
| 方法 / 関数グループ | 特徴・?? '' を渡したときの挙動 |
おすすめな場面・安全な書き方 |
|---|---|---|
文字列整形・エスケープhtmlspecialchars, trim, mb_strlen, str_contains |
空文字 "" や 0、false が返り、PHP 7.x時代の暗黙変換と完全に同じ結果になる。 |
画面表示やバリデーション前の整形。trim($val ?? '') |
文字列分割explode, str_split |
explode(',', '') は空配列 [] ではなく [''](要素数1) を返すため件数判定が狂う。 |
CSV文字列やタグの配列化。($val ?? '') !== '' ? explode(',', $val) : [] |
正規表現マッチングpreg_match, preg_replace |
空文字 "" に対してパターン検証が行われ、未マッチなら安全に 0 が返る。 |
任意入力項目の形式チェック。preg_match('/\A\d+\z/', $val ?? '') |
数値フォーマットnumber_format, round |
第1引数が float 型のため、?? ''(空文字)を渡すと TypeError で即クラッシュする。 |
金額や数量の表示処理。number_format((float)($val ?? 0)) |
JSONデコードjson_decode |
空文字 "" を渡すと、JSON_THROW_ON_ERROR 指定時に JsonException(構文エラー)が発生する。 |
NULL許容のJSONカラム解析。($val !== null && $val !== '') ? json_decode($val, true, 512, JSON_THROW_ON_ERROR) : [] |
4. 実務でハマりやすい3つの注意点
PHP 8.x への移行対応やリファクタリング時に、現場のコードレビューで特に問題になりやすいポイントを3つ整理しました。
explode(',', $str ?? '') が引き起こす空要素バグ機械的に ?? '' を追加すると explode(',', '') が [''] を返し、!empty($tags) が true になります。分割前に ($str ?? '') !== '' で空文字判定を入れるか、preg_split('/,/', $str ?? '', -1, PREG_SPLIT_NO_EMPTY) を使用してください。
declare(strict_types=1) の有無でエラーの深刻度が変わるstrict_types=1 未宣言なら Deprecated(処理継続)で済みますが、宣言済みファイルでは即座に Uncaught TypeError(処理停止)となります。後から strict_types=1 を追加する際は、PHPStan等の静的解析で事前に検査してください。
error_reporting での警告非表示は PHP 9.0 で破綻するerror_reporting(E_ALL & ~E_DEPRECATED) によるログ抑止は一時しのぎに過ぎません。次期メジャーバージョンの PHP 9.0 では strict_types の有無を問わず完全な TypeError へ昇格するため、コード側で null を解消しておく必要があります。
5. よくある質問(FAQ)
「Passing null to parameter」エラーの修正時によくある疑問とベストプラクティスをまとめました。
Q. (string)$val での型キャストと $val ?? ''(Null合体演算子)はどちらを使うべきですか?
実務では $val ?? ''(Null合体演算子) を強く推奨します。(string)$val は配列等が混入した際も無理にキャストして別警告を出しますが、?? '' なら null のみを安全に空文字へ置き換え、想定外の型ミスは正しく検知できます。
Q. 自作の関数やメソッドで引数に null を許容したい場合はどう書けばいいですか?
引数の型宣言を Nullable型(?string)にします。たとえば function sanitizeText(?string $text = null): string と定義し、関数先頭で $text ??= ''; と初期化すれば、呼び出し側で毎回 ?? '' を書く手間を省けます。
Q. LaravelのBladeテンプレート内でも同じエラーは発生しますか?
Bladeの {{ $user->bio }} は内部の e() ヘルパーが null を空文字へ変換するため警告は出ません。ただし {{ trim($user->bio) }} のように標準関数を直接呼ぶ箇所では発生するため、{{ trim($user->bio ?? '') }} と記述してください。