【PHP8.x】JSON_INVALID_UTF8_IGNORE定数の使い方

JSON_INVALID_UTF8_IGNORE定数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2026年03月08日

基本的な使い方

JSON_INVALID_UTF8_IGNORE定数は、PHPのJSON処理において、不正なUTF-8文字の扱いを制御するためのオプションを表す定数です。この定数は主に、PHPのjson_encode()関数やjson_decode()関数などのJSON関連関数に渡すことで、これらの関数の動作を変更するために使用されます。

具体的には、入力される文字列データの中に、UTF-8として正しくないバイトシーケンスが含まれていた場合、通常であればJSONのエンコードやデコード処理はエラーとなり、失敗することがあります。しかし、JSON_INVALID_UTF8_IGNORE定数を指定してJSON関連関数を実行すると、その不正なUTF-8文字シーケンスが検出された際に、エラーとして処理を中断するのではなく、その不正な部分を無視して処理を続行させることが可能になります。

このオプションは、特に外部システムから受け取ったデータなど、完全にUTF-8の標準に準拠しているか不明な入力データを処理する際に有用です。データの完全性よりも、不正な文字が含まれていても可能な限りJSONデータの生成や解析を継続したい場合に役立ちます。ただし、不正な文字が無視されるため、その部分の情報は失われることに注意が必要です。この定数を使用することで、厳密なUTF-8検証を一時的に緩和し、より柔軟なJSON処理を実現することができます。

構文(syntax)


1<?php
2$data = ['text' => 'これは不正なUTF-8バイトシーケンスを含みます' . "\xC3\x28"];
3$jsonString = json_encode($data, JSON_INVALID_UTF8_IGNORE);

引数(parameters)

引数なし

引数はありません

戻り値(return)

int

JSON_INVALID_UTF8_IGNORE は、JSONデコード時の不正なUTF-8文字を無視するための定数です。整数値 1 が返されます。

サンプルコード

PHP: JSON_INVALID_UTF8_IGNORE でJSONエンコードする


1<?php
2
3/**
4 * JSON_INVALID_UTF8_IGNORE フラグを使用した場合としない場合の
5 * json_encode の動作の違いを示すサンプルコード。
6 *
7 * このフラグは、入力文字列に不正なUTF-8バイトシーケンスが含まれる場合に、
8 * その不正なシーケンスを無視してJSONエンコードを続行するために使用されます。
9 * PHP 8.2 で非推奨となり、PHP 9.0 で削除される予定ですが、PHP 8 では利用可能です。
10 */
11function demonstrateJsonInvalidUtf8Ignore(): void
12{
13    // 不正なUTF-8バイトシーケンスを含む文字列を作成します。
14    // 例: "\xc3\x28" はUTF-8として無効な2バイトシーケンスです。
15    // (UTF-8の "\xc3" は2バイト文字の開始を示すが、続く "\x28" は有効な2バイト目の範囲外)
16    $dataWithInvalidUtf8 = [
17        'title' => '無効なバイト' . "\xc3\x28" . 'を含む文字列',
18        'description' => 'これはテスト用のデータです。',
19    ];
20
21    echo "--- 1. JSON_INVALID_UTF8_IGNORE フラグなしの場合 ---\n";
22
23    // フラグなしでjson_encodeを実行します。
24    // 不正なUTF-8バイトシーケンスが存在するため、エンコードは失敗するはずです。
25    $jsonOutputWithoutFlag = json_encode($dataWithInvalidUtf8);
26
27    // エンコード結果と最後に発生したJSONエラーを確認します。
28    if ($jsonOutputWithoutFlag === false) {
29        echo "エンコード失敗。\n";
30        echo "  エラーコード: " . json_last_error() . "\n";
31        echo "  エラーメッセージ: " . json_last_error_msg() . "\n";
32        // 通常は JSON_ERROR_UTF8 (エラーコード 5) が返されます。
33    } else {
34        echo "エンコード成功:\n";
35        echo "  結果: " . $jsonOutputWithoutFlag . "\n";
36    }
37
38    echo "\n--- 2. JSON_INVALID_UTF8_IGNORE フラグありの場合 ---\n";
39
40    // JSON_INVALID_UTF8_IGNORE フラグを付けてjson_encodeを実行します。
41    // 不正なUTF-8バイトシーケンスは無視（削除）され、エンコードが成功します。
42    $jsonOutputWithFlag = json_encode($dataWithInvalidUtf8, JSON_INVALID_UTF8_IGNORE);
43
44    // エンコード結果と最後に発生したJSONエラーを確認します。
45    if ($jsonOutputWithFlag === false) {
46        echo "エンコード失敗。\n";
47        echo "  エラーコード: " . json_last_error() . "\n";
48        echo "  エラーメッセージ: " . json_last_error_msg() . "\n";
49    } else {
50        echo "エンコード成功:\n";
51        echo "  結果: " . $jsonOutputWithFlag . "\n";
52        // 不正なバイトシーケンスが除去された状態でJSONが生成されます。
53    }
54}
55
56// 上記のデモンストレーション関数を実行します。
57demonstrateJsonInvalidUtf8Ignore();
58

JSON_INVALID_UTF8_IGNOREは、PHP 8で利用できる整数型の定数です。この定数はjson_encode関数のオプションとして使用され、入力文字列に不正なUTF-8バイトシーケンスが含まれていた場合に、その不正な部分を無視してJSONエンコードを続行させる挙動を制御します。

サンプルコードでは、不正なUTF-8バイトシーケンスを含む文字列を用意し、JSON_INVALID_UTF8_IGNOREフラグの有無によるjson_encodeの動作の違いを示しています。フラグを指定せずにjson_encodeを実行した場合、不正なUTF-8バイトシーケンスが存在するため、エンコードは失敗し、json_last_error_msg()関数を通じてエラーが報告されます。

一方、json_encodeの第2引数にJSON_INVALID_UTF8_IGNOREフラグを指定して実行すると、入力文字列中の不正なUTF-8バイトシーケンスは無視され、削除された状態でJSONエンコードが成功します。結果として、不正な部分が取り除かれた有効なJSON文字列が生成され、出力されることが確認できます。

この定数を使用することで、データの中に含まれる不完全なUTF-8文字が原因でJSONエンコードが失敗するのを避け、可能な限り有効なJSONを生成できるため、柔軟なデータ処理が必要な場面で有用です。なお、この定数はPHP 8.2で非推奨となり、PHP 9.0で削除される予定ですが、PHP 8では問題なく利用可能です。

この定数を使用すると、JSONエンコード時にデータ内の不正なUTF-8バイトシーケンスが削除されます。そのため、元のデータが一部欠損する可能性があることに注意が必要です。データの一貫性が重要な場合は、このフラグに頼る前に、入力データのUTF-8エンコーディングを正しく修正することを強く推奨いたします。また、この定数はPHP 8.2で非推奨となり、PHP 9.0で削除される予定です。将来的な互換性を考慮し、新しいプロジェクトでは使用を避け、データの前処理による根本的な解決策を検討してください。不正なバイトを無視することで、意図しない情報が失われたり、セキュリティ上の問題が発生する可能性も理解して利用することが重要です。