PHPのjson_encode完全ガイド｜使い方とオプション設定を解説

PHPのjson_encode/json_decode関数を使ったJSON形式のデータ変換方法を解説。基本的な使い方からオプション指定、日本語の文字化け対策、数値と文字列の混在時の注意点まで網羅。配列やオブジェクトをJSON形式に変換する際の実践的なサンプルコードと、よくあるエラーの解決方法が学べます。

PHPにおけるjson_encodeとは

PHPでWebアプリケーションやAPIを開発する際、データを効率的にやり取りするための手段として、JSON形式が広く使われています。json_encodeは、PHPのデータ構造をJSON形式の文字列に変換するための組み込み関数であり、現代のWeb開発において欠かせない機能の一つです。この関数を理解することで、フロントエンドとバックエンド間のデータ連携がスムーズになり、より柔軟なシステム構築が可能になります。

JSONとは何か

JSON（JavaScript Object Notation）は、データを構造化して表現するための軽量なテキストベースのフォーマットです。元々はJavaScriptのオブジェクト表記法から派生したものですが、現在ではプログラミング言語に依存しない汎用的なデータ交換形式として広く採用されています。

JSONの主な特徴は、人間にとって読み書きしやすく、機械にとっても解析や生成が容易である点です。データはキーと値のペアで表現され、オブジェクト（連想配列）や配列、文字列、数値、真偽値、nullといった基本的なデータ型をサポートしています。

JSON形式のデータ例を見てみましょう：

{
  "name": "田中太郎",
  "age": 30,
  "email": "tanaka@example.com",
  "skills": ["PHP", "JavaScript", "MySQL"]
}

このように階層的な構造を持つデータを簡潔に表現できるため、Web APIのレスポンスや設定ファイル、データベースとの連携など、さまざまな場面で活用されています。特にRESTful APIでは、標準的なデータ交換形式として採用されることが一般的です。

json_encodeの役割と目的

json_encodeは、PHPの配列やオブジェクトをJSON形式の文字列に変換（エンコード）する関数です。PHP 5.2.0以降から標準で利用可能となっており、データのシリアライズ処理を簡単に実行できます。

この関数の主な役割は、PHPで扱っているデータを他のシステムやプログラミング言語と共有可能な形式に変換することです。例えば、データベースから取得したユーザー情報をJavaScriptで処理したい場合、PHPの配列をそのまま渡すことはできません。そこでjson_encodeを使ってJSON形式に変換することで、言語の壁を越えたデータのやり取りが実現できます。

json_encodeの主な使用目的には、以下のようなケースがあります：

• Ajax通信でのデータ送信：サーバー側で処理したデータをブラウザのJavaScriptに渡す際に使用
• Web APIのレスポンス生成：外部システムやモバイルアプリに対してデータを提供する際の標準形式として利用
• データの保存：複雑なデータ構造をファイルやデータベースに保存する際のフォーマットとして活用
• ログ出力：構造化されたログデータを記録する際に可読性を高める目的で使用
• 外部サービスとの連携：他のWebサービスやAPIにデータを送信する際の形式変換に利用

json_encodeを使用することで、開発者は複雑な文字列操作を行うことなく、わずか一行のコードで確実にデータ変換を実行できます。これにより開発効率が向上し、バグの発生リスクも低減されるため、現代のPHP開発において必須のツールとなっています。

“`html

json_encodeの基本的な使い方

PHPでJSON形式のデータを生成するには、json_encode関数を使用します。この関数は、PHPの配列やオブジェクトを簡単にJSON文字列へと変換できる強力な機能を持っています。ここでは、json_encodeの基本的な構文から実際の使用例まで、順を追って解説していきます。

基本構文とパラメータ

json_encodeの基本的な構文は以下の通りです。

string|false json_encode(mixed $value, int $flags = 0, int $depth = 512)

この関数は3つのパラメータを受け取ります。第1パラメータの$valueは、JSON形式に変換したいPHPの値を指定します。配列、オブジェクト、文字列、数値、真偽値など、ほとんどのデータ型に対応しています。第2パラメータの$flagsは、変換時の動作を制御するオプションフラグで、複数のオプションをビット演算子で組み合わせて指定できます。省略した場合は0（デフォルト動作）となります。第3パラメータの$depthは、ネストされた構造の最大深度を指定し、デフォルトは512です。深くネストされたデータ構造を扱う際は、この値を調整する必要がある場合があります。

配列をJSON形式に変換する方法

PHPの配列をJSON形式に変換するのは、json_encodeの最も一般的な使用方法です。連想配列と通常の配列では、変換後のJSON形式が異なる点に注意が必要です。

連想配列はJSONオブジェクトに、数値インデックス配列はJSON配列に変換されます。以下の例で具体的に見ていきましょう。

// 数値インデックス配列の変換
$array = ['apple', 'banana', 'orange'];
$json = json_encode($array);
echo $json;
// 出力: ["apple","banana","orange"]

// 連想配列の変換
$assoc = [
    'name' => '山田太郎',
    'age' => 30,
    'email' => 'yamada@example.com'
];
$json = json_encode($assoc);
echo $json;
// 出力: {"name":"山田太郎","age":30,"email":"yamada@example.com"}

多次元配列も同様に変換可能です。配列の構造がそのままJSON形式に反映されるため、複雑なデータ構造もシンプルなコードで処理できます。

// 多次元配列の変換
$users = [
    [
        'id' => 1,
        'name' => '佐藤花子',
        'skills' => ['PHP', 'JavaScript', 'SQL']
    ],
    [
        'id' => 2,
        'name' => '鈴木一郎',
        'skills' => ['Python', 'Ruby']
    ]
];
$json = json_encode($users);
echo $json;

オブジェクトをJSON形式に変換する方法

PHPオブジェクトもjson_encodeで簡単にJSON形式に変換できます。オブジェクトの場合、publicプロパティがJSONオブジェクトのキーと値として出力されます。

以下は基本的なオブジェクトの変換例です。

class User {
    public $name;
    public $age;
    private $password;
    
    public function __construct($name, $age, $password) {
        $this->name = $name;
        $this->age = $age;
        $this->password = $password;
    }
}

$user = new User('田中次郎', 25, 'secret123');
$json = json_encode($user);
echo $json;
// 出力: {"name":"田中次郎","age":25}

重要な点として、privateやprotectedのプロパティはJSON出力に含まれません。これはセキュリティ上の利点でもありますが、すべてのプロパティを出力したい場合は、JsonSerializableインターフェースを実装する必要があります。

class Product implements JsonSerializable {
    private $id;
    private $name;
    private $price;
    
    public function __construct($id, $name, $price) {
        $this->id = $id;
        $this->name = $name;
        $this->price = $price;
    }
    
    public function jsonSerialize(): mixed {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'price' => $this->price
        ];
    }
}

$product = new Product(101, 'ノートPC', 89800);
$json = json_encode($product);
echo $json;
// 出力: {"id":101,"name":"ノートPC","price":89800}

戻り値について

json_encodeの戻り値は、成功時にはJSON形式の文字列（string型）を返し、失敗時にはfalseを返します。この動作を理解しておくことは、エラーハンドリングを適切に行う上で重要です。

変換に成功した場合、PHPのデータ構造に応じた適切なJSON文字列が生成されます。一方、変換に失敗する主なケースとしては、以下のような状況があります。

• 無限ループを含むような循環参照がある場合
• UTF-8でエンコードされていない文字列が含まれる場合
• サポートされていないデータ型（resourceなど）が含まれる場合
• 指定した深度を超えるネスト構造がある場合

エラーが発生した際には、json_last_error()関数とjson_last_error_msg()関数を使用して、エラーの詳細を確認できます。

$data = ['key' => "\xB1\x31"]; // 不正なUTF-8シーケンス
$json = json_encode($data);

if ($json === false) {
    echo 'JSON変換エラー: ' . json_last_error_msg();
    echo ' (エラーコード: ' . json_last_error() . ')';
}
// 出力例: JSON変換エラー: Malformed UTF-8 characters, possibly incorrectly encoded

PHP 7.3以降では、json_encode失敗時に例外をスローさせるJSON_THROW_ON_ERRORオプションも利用可能です。これにより、より直感的なエラー処理が実現できます。

try {
    $json = json_encode($data, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo 'JSONエラー: ' . $e->getMessage();
}

“`

“`html

json_encodeのオプション設定

PHPのjson_encode関数は、第2引数にオプションを指定することで、出力するJSON形式を細かく制御できます。オプションを適切に設定することで、日本語の文字化け防止や可読性の向上、データ型の自動変換など、さまざまなニーズに対応できます。ここでは、実務でよく使用される主要なオプションについて詳しく解説します。

主要なオプション一覧

json_encodeには多数のオプションが用意されており、それぞれ異なる役割を持っています。オプションは定数として定義されており、ビット演算子「|」を使って複数のオプションを同時に指定できます。以下に、実務で頻繁に使用される主要なオプションをまとめました。

これらのオプションを組み合わせることで、用途に応じた最適なJSON出力が可能になります。次のコード例では、複数のオプションを同時に使用する方法を示します。

<?php
$data = [
    'name' => '山田太郎',
    'age' => '25',
    'url' => 'https://example.com/path'
];

// 複数のオプションを組み合わせる
$json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT);
echo $json;
?>

JSON_UNESCAPED_UNICODEで日本語を正しく扱う

json_encodeのデフォルト動作では、日本語などのマルチバイト文字は「\uXXXX」形式のUnicodeエスケープシーケンスに変換されます。これは技術的には正しいJSON形式ですが、人間が読むには非常に不便です。JSON_UNESCAPED_UNICODEオプションを使用すると、日本語を含むUnicode文字をエスケープせずにそのまま出力できます。

以下の例で、オプション有無による出力の違いを確認してみましょう。

<?php
$data = [
    'title' => 'PHPプログラミング',
    'description' => 'json_encodeの使い方を学習する',
    'tags' => ['PHP', 'JSON', '日本語']
];

// オプションなし（デフォルト）
echo "オプションなし:\n";
echo json_encode($data) . "\n\n";
// 出力例: {"title":"PHP\u30d7\u30ed\u30b0\u30e9\u30df\u30f3\u30b0",...}

// JSON_UNESCAPED_UNICODEあり
echo "JSON_UNESCAPED_UNICODEあり:\n";
echo json_encode($data, JSON_UNESCAPED_UNICODE);
// 出力例: {"title":"PHPプログラミング",...}
?>

このオプションは特に、APIレスポンスのデバッグ時やログファイルへの出力時に有用です。ただし、非常に古いブラウザやシステムとの互換性が必要な場合は、エスケープされた形式の方が安全な場合もあります。現代的なシステム開発では、JSON_UNESCAPED_UNICODEの使用が一般的です。

JSON_PRETTY_PRINTで読みやすく整形する

JSON_PRETTY_PRINTオプションは、JSONデータに適切な改行とインデントを追加して、階層構造が視覚的にわかりやすい形式で出力します。このオプションは開発環境やデバッグ時に非常に役立ちますが、データサイズが増加するため本番環境では使い分けが必要です。

以下のコード例で、整形前後の違いを見てみましょう。

<?php
$data = [
    'user' => [
        'id' => 1001,
        'name' => '佐藤花子',
        'profile' => [
            'email' => 'hanako@example.com',
            'age' => 28,
            'hobbies' => ['読書', '旅行', 'プログラミング']
        ]
    ],
    'status' => 'active'
];

// 通常の出力（1行）
echo "通常の出力:\n";
echo json_encode($data, JSON_UNESCAPED_UNICODE) . "\n\n";

// JSON_PRETTY_PRINTで整形
echo "整形された出力:\n";
echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
?>

JSON_PRETTY_PRINTを使用した出力は、次のように階層構造が明確になります。

{
    "user": {
        "id": 1001,
        "name": "佐藤花子",
        "profile": {
            "email": "hanako@example.com",
            "age": 28,
            "hobbies": [
                "読書",
                "旅行",
                "プログラミング"
            ]
        }
    },
    "status": "active"
}

開発環境と本番環境で出力形式を切り替える場合は、環境変数や設定ファイルを使用してオプションを動的に変更する実装が推奨されます。これにより、デバッグ時の利便性と本番環境でのパフォーマンスの両立が可能になります。

JSON_NUMERIC_CHECKの注意点と使い方

JSON_NUMERIC_CHECKオプションは、文字列型で格納されている数値データを自動的に数値型に変換してJSON出力します。データベースから取得したデータや外部APIからのレスポンスなど、数値が文字列として扱われているケースで便利ですが、予期しない動作を引き起こす可能性があるため注意が必要です。

まず、基本的な使用例を見てみましょう。

<?php
$data = [
    'user_id' => '12345',
    'price' => '9800',
    'quantity' => '3',
    'postal_code' => '0001234'
];

// オプションなし
echo "オプションなし:\n";
echo json_encode($data) . "\n";
// 出力: {"user_id":"12345","price":"9800","quantity":"3","postal_code":"0001234"}

// JSON_NUMERIC_CHECKあり
echo "\nJSON_NUMERIC_CHECKあり:\n";
echo json_encode($data, JSON_NUMERIC_CHECK);
// 出力: {"user_id":12345,"price":9800,"quantity":3,"postal_code":1234}
?>

このオプションを使用する際の主な注意点は以下の通りです。

• 郵便番号や電話番号など、先頭にゼロを含む数値文字列が意図せず数値に変換され、先頭のゼロが失われる
• IDなど、数値形式であっても文字列として扱うべきデータが数値型に変換されてしまう
• 非常に大きな数値が浮動小数点数に変換され、精度が失われる可能性がある
• 科学的記数法の文字列（例：「1e5」）も数値として解釈される

これらの問題を避けるため、より安全な代替手段として、データを事前に適切な型にキャストする方法があります。

<?php
$data = [
    'user_id' => '12345',      // 文字列として保持したい
    'price' => (int)'9800',    // 明示的に整数に変換
    'quantity' => (int)'3',    // 明示的に整数に変換
    'postal_code' => '0001234' // 文字列として保持したい
];

echo json_encode($data, JSON_UNESCAPED_UNICODE);
// 出力: {"user_id":"12345","price":9800,"quantity":3,"postal_code":"0001234"}
?>

JSON_NUMERIC_CHECKは便利なオプションですが、データの性質を十分に理解した上で使用することが重要です。可能な限り、データソースの段階で適切な型に変換しておくか、個別に型キャストを行う方が安全で予測可能な動作を保証できます。特に金融データや識別番号を扱う場合は、このオプションの使用を避け、明示的な型変換を行うことを強く推奨します。

“`

“`html

json_encodeでよくある問題と解決方法

PHPでjson_encodeを使用する際には、いくつかの典型的な問題に遭遇することがあります。特に日本語を含むデータや数値の扱い、改行文字の処理などは多くの開発者が直面する課題です。ここでは、実務でよく発生する問題とその具体的な解決方法について解説します。

日本語が文字化けする場合の対処法

json_encodeを使用した際に日本語が「\u3042\u3044\u3046」のようなUnicodeエスケープシーケンスで表示されてしまう問題は、最も頻繁に発生するトラブルの一つです。これはjson_encodeのデフォルト動作で、ASCII以外の文字を自動的にエスケープするためです。

この問題を解決するには、JSON_UNESCAPED_UNICODEオプションを使用します。以下のコード例をご覧ください。

<?php
$data = array(
    'name' => '山田太郎',
    'message' => 'こんにちは'
);

// デフォルトの動作（Unicodeエスケープされる）
echo json_encode($data);
// 出力: {"name":"\u5c71\u7530\u592a\u90ce","message":"\u3053\u3093\u306b\u3061\u306f"}

// JSON_UNESCAPED_UNICODEオプションを使用
echo json_encode($data, JSON_UNESCAPED_UNICODE);
// 出力: {"name":"山田太郎","message":"こんにちは"}
?>

また、データベースから取得したデータの文字コードが適切でない場合も文字化けの原因となります。PHPスクリプトの文字エンコーディングがUTF-8であることを確認し、データベース接続時にも文字コードを明示的に設定することが重要です。ファイルの先頭に以下のような指定を追加することで、多くの文字化け問題を防ぐことができます。

<?php
header('Content-Type: application/json; charset=UTF-8');
$data = ['日本語' => 'テスト'];
echo json_encode($data, JSON_UNESCAPED_UNICODE);
?>

数値と文字列が混在する場合の注意点

PHPは型の扱いが柔軟な言語ですが、json_encodeを使用する際には数値と文字列の区別が重要になります。特に、データベースから取得した数値が文字列として扱われてしまうケースや、逆に数値として扱いたくないデータが数値に変換されてしまうケースには注意が必要です。

JSON_NUMERIC_CHECKオプションを使用すると、数値に見える文字列を自動的に数値型に変換できますが、このオプションには予期しない動作を引き起こすリスクがあります。

<?php
$data = array(
    'id' => '123',
    'zip_code' => '0001234',  // 郵便番号（先頭の0を保持したい）
    'price' => '1500'
);

// JSON_NUMERIC_CHECKなし
echo json_encode($data);
// 出力: {"id":"123","zip_code":"0001234","price":"1500"}

// JSON_NUMERIC_CHECKあり
echo json_encode($data, JSON_NUMERIC_CHECK);
// 出力: {"id":123,"zip_code":1234,"price":1500}
// 郵便番号の先頭の0が失われてしまう
?>

上記の例のように、郵便番号や電話番号など先頭に0を含むデータは、数値に変換されると意図しない結果になります。推奨される対処法は、データ準備の段階で明示的に型キャストを行うことです。

<?php
$data = array(
    'id' => (int)'123',        // 明示的に整数型に変換
    'zip_code' => '0001234',   // 文字列として保持
    'price' => (float)'1500.5' // 明示的に浮動小数点型に変換
);

echo json_encode($data);
// 出力: {"id":123,"zip_code":"0001234","price":1500.5}
?>

また、nullと空文字列、0とfalseなども区別して扱う必要があります。これらの値は意味が異なるため、適切にデータ型を維持することがAPIの品質向上につながります。

改行を適切に処理する方法

テキストエリアから入力されたデータや複数行のメッセージを含むデータをjson_encodeで処理する際、改行コードの扱いに困ることがあります。json_encodeは改行コードを自動的にエスケープシーケンス（\nや\r\n）に変換しますが、この動作を理解していないと問題が発生する可能性があります。

PHPのjson_encodeは改行を含むデータを以下のように処理します。

<?php
$data = array(
    'message' => "こんにちは\nこれは改行を含むテキストです\nよろしくお願いします"
);

echo json_encode($data, JSON_UNESCAPED_UNICODE);
// 出力: {"message":"こんにちは\nこれは改行を含むテキストです\nよろしくお願いします"}
?>

JSON形式では改行は「\n」として正しくエスケープされるため、基本的には特別な処理は不要です。しかし、HTMLとして表示する際やJavaScriptで処理する際には注意が必要になります。

フォームから送信されたデータに含まれる改行コードは、OSによって異なる場合があります（Windows: \r\n、Unix/Linux: \n、Mac: \r）。これらを統一して処理したい場合は、以下のような方法が有効です。

<?php
$input = $_POST['message'];

// 改行コードを統一する
$normalized = str_replace(array("\r\n", "\r"), "\n", $input);

$data = array('message' => $normalized);
echo json_encode($data, JSON_UNESCAPED_UNICODE);
?>

また、JSON_UNESCAPED_SLASHESオプションと組み合わせることで、URLやパスを含むデータの可読性を向上させることもできます。改行を含むデータをデバッグしやすくするには、JSON_PRETTY_PRINTオプションも併用すると効果的です。

<?php
$data = array(
    'title' => 'サンプル',
    'content' => "1行目\n2行目\n3行目"
);

echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
/* 出力:
{
    "title": "サンプル",
    "content": "1行目\n2行目\n3行目"
}
*/
?>

ただし、改行を含むデータをHTMLで表示する場合は、JavaScriptやPHP側でnl2br関数などを使用して適切にHTML改行タグに変換する必要があります。JSON形式では改行が保持されていても、ブラウザでの表示には別途処理が必要という点に留意してください。

“`

“`html

json_decodeによるデコード処理

json_encodeで作成されたJSON形式のデータをPHPで扱うには、json_decodeを使ってデコード（復元）する必要があります。このセクションでは、JSON文字列をPHPのデータ構造に変換する方法と、その際のエラーハンドリングについて詳しく解説します。json_decodeを適切に使用することで、外部APIからのレスポンスやファイルから読み込んだJSONデータを効率的に処理できるようになります。

json_decodeの基本的な使い方

json_decodeは、JSON形式の文字列をPHPで扱えるデータ型に変換する関数です。基本的な構文は以下のようになります。

json_decode(string $json, ?bool $associative = null, int $depth = 512, int $flags = 0): mixed

最もシンプルな使い方は、JSON文字列を第一引数に指定するだけです。以下は基本的な使用例です。

$json = '{"name":"田中太郎","age":30,"city":"東京"}';
$result = json_decode($json);
echo $result->name; // 出力: 田中太郎

json_decodeには複数のパラメータがあり、それぞれ以下のような役割を持ちます。

• $json：デコード対象のJSON文字列（必須）
• $associative：trueにすると連想配列として返却、falseまたはnullでオブジェクトとして返却
• $depth：ネストの最大深度を指定（デフォルト512）
• $flags：ビットマスクオプション（JSON_BIGINT_AS_STRINGなど）

デコードに失敗した場合はnullが返されるため、後述するエラーハンドリングと組み合わせて使用することが推奨されます。

JSONデータをPHP配列に変換する

json_decodeの第二引数にtrueを指定することで、JSONデータを連想配列として取得できます。この方法は配列としてデータを扱いたい場合に非常に便利です。

$json = '{"name":"山田花子","age":25,"skills":["PHP","JavaScript","Python"]}';
$array = json_decode($json, true);

echo $array['name']; // 出力: 山田花子
echo $array['skills'][0]; // 出力: PHP

配列形式での取得は、以下のような利点があります。

• 配列関数（array_map、array_filterなど）を直接使用できる
• isset()やempty()での存在チェックが容易
• キーの存在確認が$array[‘key’] ?? ‘default’のように簡潔に記述できる
• foreachでの反復処理が直感的

$json = '[
    {"id":1,"product":"ノートPC","price":120000},
    {"id":2,"product":"マウス","price":3000},
    {"id":3,"product":"キーボード","price":8000}
]';

$products = json_decode($json, true);

foreach ($products as $product) {
    echo "{$product['product']}: {$product['price']}円\n";
}

特にデータベースからの取得結果やAPIレスポンスを処理する際は、配列形式の方が扱いやすいケースが多く、実務でも広く使われています。

JSONデータをPHPオブジェクトに変換する

json_decodeの第二引数を省略するか、falseを指定すると、JSONデータはstdClassオブジェクトとして返却されます。オブジェクト形式での取得は、データ構造を明確に表現したい場合に適しています。

$json = '{"name":"佐藤一郎","email":"sato@example.com","active":true}';
$object = json_decode($json);

echo $object->name; // 出力: 佐藤一郎
echo $object->email; // 出力: sato@example.com
var_dump($object->active); // 出力: bool(true)

オブジェクト形式は以下のような特徴があります。

• プロパティへのアクセスがアロー演算子（->）で直感的
• JSONの階層構造がオブジェクトの階層として保持される
• 型情報が保持される（bool、int、floatなど）
• IDE（統合開発環境）での補完が効きやすい場合がある

$json = '{
    "user": {
        "id": 123,
        "profile": {
            "firstName": "健太",
            "lastName": "鈴木",
            "age": 28
        }
    }
}';

$data = json_decode($json);
echo $data->user->profile->firstName; // 出力: 健太
echo $data->user->profile->age; // 出力: 28

ネストされたJSONデータを扱う場合、オブジェクト形式の方がコードの可読性が高くなる傾向があります。ただし、プロパティの存在確認にはproperty_exists()やisset()を使う必要がある点に注意が必要です。

エラーハンドリングの方法

json_decodeは不正なJSON文字列を受け取るとnullを返しますが、正常なJSONでもnullという値を持つ場合があるため、単純なnullチェックでは不十分です。正確なエラー検知には、json_last_error()またはjson_last_error_msg()を使用します。

$json = '{"name":"太郎", "age":30,}'; // 不正なJSON（末尾のカンマ）
$result = json_decode($json);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "JSONデコードエラー: " . json_last_error_msg();
    // 出力: JSONデコードエラー: Syntax error
}

json_last_error()が返す主なエラーコードは以下の通りです。

より実践的なエラーハンドリングの実装例を以下に示します。

function safeJsonDecode($json, $assoc = false) {
    $result = json_decode($json, $assoc);
    
    if (json_last_error() !== JSON_ERROR_NONE) {
        $errorMsg = json_last_error_msg();
        throw new Exception("JSON decode error: {$errorMsg}");
    }
    
    return $result;
}

try {
    $data = safeJsonDecode('{"invalid json}');
} catch (Exception $e) {
    echo "エラーが発生しました: " . $e->getMessage();
    // エラーログの記録やデフォルト値の設定などの処理
}

PHP 7.3以降では、JSON_THROW_ON_ERRORフラグを使用することで、エラー時に自動的に例外をスローさせることができます。

try {
    $result = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo "JSONエラー: " . $e->getMessage();
}

この方法を使えば、json_last_error()を明示的にチェックする必要がなくなり、より簡潔で安全なコードが書けます。外部APIからのデータやユーザー入力をデコードする際は、必ずエラーハンドリングを実装することが重要です。

“`

“`html

JSONファイルの読み込みと書き込み

PHPでjson_encodeを活用する際、単にデータを変換するだけでなく、JSONファイルとして保存したり、既存のJSONファイルから読み込んだりする処理が必要になる場面が多くあります。設定ファイルやデータベースの代わりとしてJSONファイルを利用するケースや、他のシステムとのデータ連携を行う場合など、ファイル操作は実務において欠かせないスキルです。このセクションでは、PHPでJSONファイルを扱う方法について、書き込みと読み込みの両面から詳しく解説していきます。

JSONファイルへの書き込み方法

PHPでjson_encodeを使ってJSON形式に変換したデータをファイルに保存するには、file_put_contents関数と組み合わせて使用します。この方法は非常にシンプルで、わずか数行のコードでJSONファイルの作成が可能です。

基本的な書き込みの手順は以下の通りです。まず、PHPの配列やオブジェクトを用意し、json_encodeでJSON文字列に変換してから、file_put_contents関数でファイルに書き込みます。

<?php
$data = [
    'name' => '山田太郎',
    'age' => 30,
    'email' => 'yamada@example.com',
    'hobbies' => ['読書', '旅行', 'プログラミング']
];

// JSON形式に変換
$json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);

// ファイルに書き込み
file_put_contents('user_data.json', $json);
?>

JSON_UNESCAPED_UNICODEオプションを使用することで、日本語などのマルチバイト文字が正しく保存されます。また、JSON_PRETTY_PRINTオプションを追加すると、人間が読みやすい形式で整形されたJSONファイルが生成されます。

書き込み処理では、エラーハンドリングを適切に行うことが重要です。ファイルの書き込み権限がない場合や、ディスク容量が不足している場合など、様々な理由で書き込みが失敗する可能性があります。

<?php
$data = ['status' => 'success', 'message' => '処理が完了しました'];
$json = json_encode($data, JSON_UNESCAPED_UNICODE);

if ($json === false) {
    die('JSONエンコードに失敗しました: ' . json_last_error_msg());
}

$result = file_put_contents('result.json', $json);

if ($result === false) {
    die('ファイルの書き込みに失敗しました');
} else {
    echo "{$result}バイトのデータを書き込みました";
}
?>

既存のJSONファイルにデータを追記したい場合は、まず既存のファイルを読み込んでデコードし、新しいデータを追加してから再度エンコードして保存する必要があります。

<?php
// 既存のJSONファイルを読み込み
$jsonString = file_get_contents('users.json');
$users = json_decode($jsonString, true) ?: [];

// 新しいユーザーを追加
$newUser = [
    'id' => count($users) + 1,
    'name' => '佐藤花子',
    'registered_at' => date('Y-m-d H:i:s')
];
$users[] = $newUser;

// 更新したデータを保存
$json = json_encode($users, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
file_put_contents('users.json', $json);
?>

JSONファイルからのデータ読み込み方法

JSONファイルからデータを読み込む処理は、file_get_contents関数でファイルの内容を文字列として取得し、json_decodeでPHPのデータ構造に変換することで実現できます。この一連の流れは、外部システムから提供されたJSONファイルを処理する場合や、設定ファイルを読み込む場合に頻繁に使用されます。

基本的な読み込み処理の例を見てみましょう。

<?php
// JSONファイルを読み込み
$jsonString = file_get_contents('user_data.json');

// JSON文字列をPHP配列に変換
$data = json_decode($jsonString, true);

if ($data === null) {
    die('JSONのデコードに失敗しました: ' . json_last_error_msg());
}

// データの利用
echo "名前: " . $data['name'] . "\n";
echo "年齢: " . $data['age'] . "\n";
?>

json_decodeの第二引数にtrueを指定すると、連想配列として取得できます。falseまたは省略した場合はオブジェクトとして取得されるため、用途に応じて使い分けることができます。

ファイルが存在しない場合や、読み込み権限がない場合のエラー処理も重要です。より堅牢な読み込み処理は以下のようになります。

<?php
$filename = 'config.json';

// ファイルの存在チェック
if (!file_exists($filename)) {
    die("ファイル {$filename} が見つかりません");
}

// ファイルが読み込み可能かチェック
if (!is_readable($filename)) {
    die("ファイル {$filename} を読み込む権限がありません");
}

// ファイルを読み込み
$jsonString = file_get_contents($filename);

if ($jsonString === false) {
    die("ファイルの読み込みに失敗しました");
}

// JSONをデコード
$config = json_decode($jsonString, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    die('JSON解析エラー: ' . json_last_error_msg());
}

// 設定値を利用
echo "データベースホスト: " . $config['database']['host'];
?>

大きなJSONファイルを扱う場合は、メモリ使用量に注意が必要です。ファイルサイズが大きい場合は、一度にすべてを読み込むのではなく、ストリーム処理を検討するか、JSONファイルの構造を見直すことも検討しましょう。

複数のJSONファイルを一括で処理する場合の実装例も紹介します。

<?php
$directory = 'json_data/';
$jsonFiles = glob($directory . '*.json');
$allData = [];

foreach ($jsonFiles as $file) {
    $jsonString = file_get_contents($file);
    $data = json_decode($jsonString, true);
    
    if ($data !== null) {
        $allData[basename($file, '.json')] = $data;
    } else {
        echo "警告: {$file} の読み込みに失敗しました\n";
    }
}

// すべてのJSONデータが統合された配列
print_r($allData);
?>

JSONファイルの読み込み時は、信頼できないソースから取得したデータを扱う場合、セキュリティに十分注意してください。特に、ユーザーがアップロードしたJSONファイルを処理する場合は、バリデーション処理を必ず実装し、想定外のデータ構造や悪意のあるコードが含まれていないかを確認することが重要です。

“`

json_encodeの実践的な活用例

PHPのjson_encode関数は、実際のWeb開発において様々な場面で活用されています。特にフロントエンドとの連携やAPI開発では欠かせない機能となっており、適切に使いこなすことで効率的なデータのやり取りが可能になります。ここでは、実務でよく使われる代表的な活用シーンを具体的なコードとともに紹介します。

Ajax通信でのJSON出力

Ajax通信では、ページをリロードせずにサーバーとデータをやり取りするため、PHPからJSON形式でデータを返すことが一般的です。json_encodeを使うことで、データベースから取得した情報を簡単にJSON形式に変換してフロントエンドに渡すことができます。

以下は、ユーザー情報を取得してAjax通信で返す典型的な例です。

<?php
header('Content-Type: application/json; charset=utf-8');

// データベースからユーザー情報を取得したと仮定
$users = [
    ['id' => 1, 'name' => '山田太郎', 'email' => 'yamada@example.com'],
    ['id' => 2, 'name' => '佐藤花子', 'email' => 'sato@example.com'],
    ['id' => 3, 'name' => '鈴木一郎', 'email' => 'suzuki@example.com']
];

// JSON形式で出力
echo json_encode($users, JSON_UNESCAPED_UNICODE);
?>

フロントエンド側のJavaScriptでは、fetchやaxiosなどを使ってこのデータを受け取ります。重要なのは、PHPファイルの冒頭でContent-Typeヘッダーを適切に設定することです。これにより、ブラウザがレスポンスをJSON形式として正しく認識できます。

// JavaScript側の処理例
fetch('users.php')
    .then(response => response.json())
    .then(data => {
        console.log(data); // PHPから受け取ったユーザー情報
        // データを使った処理を記述
    });

エラー処理を含めた、より実践的な例も見てみましょう。

<?php
header('Content-Type: application/json; charset=utf-8');

try {
    // 処理が成功した場合
    $result = [
        'status' => 'success',
        'data' => [
            'message' => '処理が完了しました',
            'items' => ['item1', 'item2', 'item3']
        ]
    ];
    echo json_encode($result, JSON_UNESCAPED_UNICODE);
    
} catch (Exception $e) {
    // エラーが発生した場合
    $error = [
        'status' => 'error',
        'message' => $e->getMessage()
    ];
    http_response_code(500);
    echo json_encode($error, JSON_UNESCAPED_UNICODE);
}
?>

APIレスポンスの生成

RESTful APIの開発において、json_encodeはレスポンスデータを生成する中心的な役割を担います。APIでは、統一されたフォーマットでデータを返すことが重要であり、JSON形式は最も広く使われている標準フォーマットです。

APIレスポンスでは、ステータスコード、メタ情報、実際のデータなどを構造化して返すことが一般的です。

<?php
header('Content-Type: application/json; charset=utf-8');

// APIレスポンスの基本構造
function apiResponse($data, $statusCode = 200, $message = '') {
    http_response_code($statusCode);
    
    $response = [
        'status' => $statusCode < 400 ? 'success' : 'error',
        'code' => $statusCode,
        'message' => $message,
        'data' => $data,
        'timestamp' => date('Y-m-d H:i:s')
    ];
    
    echo json_encode($response, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
    exit;
}

// 使用例：商品情報を返すAPI
$products = [
    [
        'id' => 101,
        'name' => 'ノートPC',
        'price' => 89800,
        'stock' => 15
    ],
    [
        'id' => 102,
        'name' => 'ワイヤレスマウス',
        'price' => 2980,
        'stock' => 50
    ]
];

apiResponse($products, 200, '商品一覧の取得に成功しました');
?>

JSON_PRETTY_PRINTオプションを使用することで、開発中のデバッグが容易になります。本番環境では、パフォーマンスを考慮して不要な場合もありますが、APIドキュメントやテスト時には有用です。

より複雑なAPIレスポンスでは、ページネーション情報も含めることがあります。

<?php
$response = [
    'status' => 'success',
    'data' => [
        'items' => $products,
        'pagination' => [
            'current_page' => 1,
            'per_page' => 20,
            'total' => 150,
            'total_pages' => 8
        ]
    ],
    'meta' => [
        'api_version' => '1.0',
        'request_id' => uniqid()
    ]
];

echo json_encode($response, JSON_UNESCAPED_UNICODE);
?>

JavaScriptとの連携方法

PHPとJavaScriptの連携において、json_encodeは両者の橋渡しとなる重要な機能です。PHPで生成したデータをJavaScriptで直接利用できる形式に変換することで、動的なWebページを効率的に構築できます。

最も基本的な連携方法は、PHPからHTMLに埋め込む形でJavaScriptの変数にデータを渡す方法です。

<?php
$config = [
    'apiUrl' => 'https://api.example.com',
    'timeout' => 5000,
    'locale' => 'ja_JP',
    'features' => ['search', 'filter', 'export']
];
?>

<script>
// PHPのデータをJavaScriptの変数として展開
const appConfig = <?php echo json_encode($config, JSON_UNESCAPED_UNICODE); ?>;

console.log(appConfig.apiUrl); // https://api.example.com
console.log(appConfig.features); // ['search', 'filter', 'export']
</script>

ただし、この方法を使う場合、XSS攻撃を防ぐために必ずデータのサニタイズが必要です。特にユーザー入力を含むデータを扱う場合は、JSON_HEX_TAGやJSON_HEX_AMP、JSON_HEX_APOSなどのオプションを組み合わせて使用しましょう。

<?php
// セキュアな方法でデータを渡す
$userData = [
    'username' => htmlspecialchars($username, ENT_QUOTES, 'UTF-8'),
    'settings' => $userSettings
];

$jsonOptions = JSON_UNESCAPED_UNICODE | JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT;
?>

<script>
const userData = <?php echo json_encode($userData, $jsonOptions); ?>;
</script>

複雑なデータ構造を扱う場合の実例も見てみましょう。

<?php
// グラフ描画用のデータを準備
$chartData = [
    'labels' => ['1月', '2月', '3月', '4月', '5月'],
    'datasets' => [
        [
            'label' => '売上',
            'data' => [120, 150, 180, 170, 200],
            'backgroundColor' => 'rgba(75, 192, 192, 0.2)',
            'borderColor' => 'rgba(75, 192, 192, 1)'
        ]
    ],
    'options' => [
        'responsive' => true,
        'maintainAspectRatio' => false
    ]
];
?>

<script>
const chartData = <?php echo json_encode($chartData, JSON_UNESCAPED_UNICODE); ?>;

// Chart.jsなどのライブラリで使用
// new Chart(ctx, {
//     type: 'line',
//     data: chartData,
//     options: chartData.options
// });
</script>

また、データ属性（data-*属性）を使ってHTML要素にJSONデータを埋め込む方法も便利です。

<?php
$productInfo = [
    'id' => 12345,
    'name' => 'サンプル商品',
    'price' => 5980,
    'stock' => 30
];
?>

<div id="product" data-info='<?php echo json_encode($productInfo, JSON_UNESCAPED_UNICODE | JSON_HEX_APOS); ?>'>
    <!-- 商品表示 -->
</div>

<script>
const productElement = document.getElementById('product');
const productData = JSON.parse(productElement.dataset.info);
console.log(productData.price); // 5980
</script>

このように、json_encodeを活用することで、PHPとJavaScript間でシームレスにデータをやり取りすることができます。適切なオプションを選択し、セキュリティにも配慮しながら実装することが重要です。

“`html

まとめ

PHPのjson_encodeは、配列やオブジェクトをJSON形式の文字列に変換するための関数であり、Web開発における重要な機能の一つです。Ajax通信やAPI開発、JavaScriptとのデータ連携など、現代のWebアプリケーション開発において欠かせないツールとなっています。

この記事では、json_encodeの基本的な使い方から実践的な活用方法まで幅広く解説してきました。重要なポイントを以下にまとめます。

• json_encodeは配列やオブジェクトをJSON形式に変換し、システム間のデータ受け渡しを可能にする
• オプション設定を活用することで、日本語の扱いや出力形式を柔軟にカスタマイズできる
• JSON_UNESCAPED_UNICODEオプションは日本語の文字化けを防ぎ、可読性を向上させる
• JSON_PRETTY_PRINTオプションを使用すると、整形された読みやすいJSON出力が得られる
• json_decodeと組み合わせることで、JSONデータの双方向変換が実現できる

実際の開発現場では、Ajax通信やAPIレスポンスの生成など、フロントエンドとバックエンドの橋渡し役としてjson_encodeが活躍します。特にJavaScriptとの連携においては、PHPで処理したデータをJSON形式で出力することで、シームレスなデータ交換が可能になります。

一方で、日本語の文字化けや数値と文字列の混在、改行コードの処理など、注意すべき点も存在します。適切なオプション設定とエラーハンドリングを行わないと、予期しない動作やデータの破損につながる可能性があります。本記事で紹介した対処法を参考に、堅牢なコードを実装することを心がけてください。

json_encodeを正しく理解し活用することで、より効率的で保守性の高いWebアプリケーション開発が可能になります。基本的な使い方を押さえた上で、プロジェクトの要件に応じて適切なオプションを選択し、実践的な開発に役立ててください。

“`