PHPで文字列をJSON形式に変換する方法を徹底解説（json_encode）

PHPでの開発において、データを交換するための形式としてJSON（JavaScript Object Notation）は非常に重要です。特に、Web APIの開発やフロントエンドとバックエンドの通信において、データを効率的にやり取りするための標準的なフォーマットとして広く採用されています。

PHPでは、json_encode関数を使用することで、文字列や配列、オブジェクトを簡単にJSON形式に変換することができます。本記事では、JSON形式の基本的な理解から、PHPでのjson_encode関数の使い方、応用例までを徹底的に解説します。これにより、PHPでのJSONの取り扱いをマスターし、開発の幅を広げることができるでしょう。

JSON形式とは

JSON（JavaScript Object Notation）は、データを構造化して保存・交換するための軽量なフォーマットです。人間が読み書きしやすく、機械で解析しやすい構造を持ち、キーと値のペアでデータを表現します。

JSONの基本構造

JSONは、オブジェクトと配列を用いてデータを表現します。オブジェクトは波括弧 {} で囲み、キーと値のペアでデータを定義します。配列は角括弧 [] で囲み、複数の値をリスト形式で表現します。

例：JSONオブジェクト

{
    "name": "Taro",
    "age": 25,
    "skills": ["PHP", "JavaScript", "HTML"]
}

JSONの用途

JSONは、以下のような用途で広く利用されています。

• Web APIのデータ交換：サーバーとクライアント間でデータをやり取りする際のフォーマット。
• 設定ファイル：アプリケーションの設定情報を格納する形式。
• データストレージ：データベースの代替として、一時的なデータ保存に使用されることもあります。

JSONは、そのシンプルさと汎用性から、さまざまなプログラミング言語でサポートされており、データ交換の標準フォーマットとして定着しています。

PHPにおけるJSONの役割

PHPでJSONを扱うことは、Web開発において非常に重要です。特に、サーバーサイドとクライアントサイド間のデータ交換や外部APIとの連携など、多くの場面でJSON形式が利用されています。PHPは、JSONを簡単に操作するための組み込み関数を提供しており、その中でもjson_encodeやjson_decodeが頻繁に使用されます。

PHPでJSONが必要とされる場面

PHPでJSONがよく利用される具体的なケースを以下に紹介します。

Web APIとの通信

Web APIでは、データの送受信にJSON形式を使用するのが一般的です。PHPからAPIを呼び出したり、PHPでAPIを実装したりする場合、JSONを利用してデータのやり取りを行います。

フロントエンドとのデータ交換

Ajaxを使用した非同期通信やJavaScriptライブラリ（例：Vue.js、React）との連携において、サーバーからクライアントにデータを渡す際にJSON形式が使われます。PHPで生成したデータをjson_encodeで変換し、クライアント側で受け取って処理するのが一般的です。

設定ファイルやログの保存

JSON形式を使用して、アプリケーションの設定情報やログをファイルに保存することもあります。設定ファイルをJSONで記述することで、人間にも読みやすく、プログラムでの解析も容易です。

PHPでJSONを利用するメリット

• シンプルで軽量：データフォーマットがシンプルで、通信量を節約できます。
• 他言語との互換性：多くのプログラミング言語でサポートされており、データの交換が容易です。
• 柔軟なデータ構造：ネストされたオブジェクトや配列を持つ複雑なデータ構造を扱うことが可能です。

PHPにおけるJSONの利用は、データの交換を円滑にし、アプリケーションの柔軟性と拡張性を高めます。

json_encode関数の基本的な使い方

json_encode関数は、PHPのデータ（配列やオブジェクトなど）をJSON形式の文字列に変換するために使用されます。この関数を使うことで、サーバーサイドのデータを簡単にクライアントに送信できる形式に変換することが可能です。

基本的な構文

json_encode関数の基本的な構文は以下のとおりです。

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

• $value：変換したいPHPデータ（配列やオブジェクト）
• $options（任意）：エンコード時のオプションを指定（例：JSON_PRETTY_PRINT）
• $depth（任意）：エンコードする際の最大深度（デフォルトは512）

基本的な使用例

以下は、配列をJSON形式に変換する例です。

$data = array(
    "name" => "Taro",
    "age" => 25,
    "skills" => array("PHP", "JavaScript", "HTML")
);

$json = json_encode($data);
echo $json;

この例では、以下のようなJSON文字列が出力されます。

{"name":"Taro","age":25,"skills":["PHP","JavaScript","HTML"]}

オプションの利用例

オプションを使用することで、出力形式を調整することも可能です。たとえば、JSON_PRETTY_PRINTを指定すると、整形された見やすいJSON文字列を生成できます。

$json_pretty = json_encode($data, JSON_PRETTY_PRINT);
echo $json_pretty;

出力結果は以下のようになります。

{
    "name": "Taro",
    "age": 25,
    "skills": [
        "PHP",
        "JavaScript",
        "HTML"
    ]
}

json_encode関数を活用することで、PHPのデータを効率よくJSON形式に変換することが可能になります。

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

PHPの配列をjson_encode関数でJSON形式に変換するのは簡単で、データのやり取りにおいて非常に便利です。特に、Webアプリケーションでサーバーからクライアントにデータを送信する際によく使われます。

数値配列をJSONに変換する

数値のみのシンプルな配列をJSON形式に変換する例を以下に示します。

$numbers = array(1, 2, 3, 4, 5);
$json_numbers = json_encode($numbers);
echo $json_numbers;

このコードを実行すると、以下のようなJSON文字列が生成されます。

[1,2,3,4,5]

連想配列をJSONに変換する

PHPの連想配列をJSON形式に変換する場合も、同じくjson_encode関数を使用します。

$user = array(
    "name" => "Taro",
    "age" => 25,
    "email" => "taro@example.com"
);

$json_user = json_encode($user);
echo $json_user;

出力結果は以下の通りです。

{"name":"Taro","age":25,"email":"taro@example.com"}

多次元配列をJSONに変換する

多次元配列（配列の中に配列が含まれている構造）も、json_encodeで簡単にJSON形式に変換できます。

$users = array(
    array(
        "name" => "Taro",
        "age" => 25,
        "email" => "taro@example.com"
    ),
    array(
        "name" => "Hanako",
        "age" => 30,
        "email" => "hanako@example.com"
    )
);

$json_users = json_encode($users, JSON_PRETTY_PRINT);
echo $json_users;

この場合の出力は、整形されたJSONとなります。

[
    {
        "name": "Taro",
        "age": 25,
        "email": "taro@example.com"
    },
    {
        "name": "Hanako",
        "age": 30,
        "email": "hanako@example.com"
    }
]

json_encodeを使うことで、シンプルな配列から複雑な多次元配列まで簡単にJSON形式に変換できるため、さまざまなシチュエーションで利用可能です。

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

PHPでは、オブジェクトもjson_encode関数を使用してJSON形式に変換できます。これにより、クラスインスタンスのデータをJSONとして扱えるようになり、Web APIのレスポンスやフロントエンドとのデータ交換がスムーズに行えます。

標準クラスオブジェクトをJSONに変換する

PHPの標準クラス（stdClass）オブジェクトをJSONに変換する例を示します。

$person = new stdClass();
$person->name = "Taro";
$person->age = 25;
$person->email = "taro@example.com";

$json_person = json_encode($person);
echo $json_person;

このコードの出力は以下の通りです。

{"name":"Taro","age":25,"email":"taro@example.com"}

標準クラスオブジェクトも配列と同様に、キーと値のペアをそのままJSON形式に変換できます。

カスタムクラスオブジェクトをJSONに変換する

カスタムクラスのオブジェクトもjson_encodeで変換可能ですが、クラスのプロパティが公開（public）されている必要があります。以下の例では、カスタムクラスのインスタンスをJSONに変換します。

class User {
    public $name;
    public $age;
    public $email;

    public function __construct($name, $age, $email) {
        $this->name = $name;
        $this->age = $age;
        $this->email = $email;
    }
}

$user = new User("Hanako", 30, "hanako@example.com");
$json_user = json_encode($user);
echo $json_user;

出力結果は次のようになります。

{"name":"Hanako","age":30,"email":"hanako@example.com"}

プライベートプロパティを含むオブジェクトの変換

オブジェクトのプロパティが非公開（private/protected）の場合、通常のjson_encodeではそのプロパティは出力されません。非公開プロパティを含むオブジェクトを変換するためには、クラスにJsonSerializableインターフェースを実装する必要があります。

class Product implements JsonSerializable {
    private $name;
    private $price;

    public function __construct($name, $price) {
        $this->name = $name;
        $this->price = $price;
    }

    public function jsonSerialize() {
        return [
            'name' => $this->name,
            'price' => $this->price
        ];
    }
}

$product = new Product("Laptop", 1500);
$json_product = json_encode($product);
echo $json_product;

出力は以下の通りです。

{"name":"Laptop","price":1500}

オブジェクトをJSON形式に変換する方法を理解することで、より柔軟にデータを取り扱うことができ、PHPでのデータ処理がより強力になります。

json_encode関数のオプション設定

json_encode関数には、エンコードの動作をカスタマイズするためのオプションが用意されています。これらのオプションを利用することで、出力されるJSONの形式を制御し、特定の要件に応じた変換が可能です。複数のオプションを組み合わせて使用することもできます。

主要なオプション一覧

以下は、json_encodeで利用できる主なオプションです。

1. `JSON_PRETTY_PRINT`

出力されるJSONを整形し、人間が読みやすい形式にします。通常はデバッグやログ出力時に利用します。

$data = array("name" => "Taro", "age" => 25);
$json_pretty = json_encode($data, JSON_PRETTY_PRINT);
echo $json_pretty;

出力結果は次のようになります。

{
    "name": "Taro",
    "age": 25
}

2. `JSON_UNESCAPED_UNICODE`

通常、json_encodeは非ASCII文字（日本語など）をエスケープしますが、このオプションを指定するとエスケープせずにそのまま出力します。

$data = array("greeting" => "こんにちは");
$json_unicode = json_encode($data, JSON_UNESCAPED_UNICODE);
echo $json_unicode;

出力結果は以下の通りです。

{"greeting":"こんにちは"}

3. `JSON_UNESCAPED_SLASHES`

スラッシュ文字（/）をエスケープせずにそのまま出力します。通常はスラッシュが\でエスケープされますが、このオプションを使うとエスケープを回避できます。

$data = array("url" => "https://example.com");
$json_slashes = json_encode($data, JSON_UNESCAPED_SLASHES);
echo $json_slashes;

結果は次のようになります。

{"url":"https://example.com"}

4. `JSON_NUMERIC_CHECK`

数値の文字列を数値としてエンコードします。このオプションを指定することで、数値を含む文字列がそのまま数値として扱われます。

$data = array("price" => "1500");
$json_numeric = json_encode($data, JSON_NUMERIC_CHECK);
echo $json_numeric;

出力は次の通りです。

{"price":1500}

複数オプションの組み合わせ

複数のオプションを組み合わせるにはビット演算子（|）を使用します。以下の例では、JSON_PRETTY_PRINTとJSON_UNESCAPED_UNICODEを組み合わせています。

$data = array("name" => "Taro", "greeting" => "こんにちは");
$json_combined = json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
echo $json_combined;

結果は整形され、日本語もエスケープされません。

{
    "name": "Taro",
    "greeting": "こんにちは"
}

json_encode関数のオプションを活用することで、JSON出力の柔軟な制御が可能となり、さまざまな用途に対応できます。

エンコード時のエラー処理方法

json_encode関数を使用する際、エンコード中にエラーが発生することがあります。エラーの原因を特定し、適切に対処することで、より安定したアプリケーションを作成できます。PHPでは、エンコードエラーの検出とエラーメッセージの取得に専用の関数が用意されています。

エラーの検出方法

json_encode関数が失敗した場合、falseが返されます。また、json_last_error関数を使用することで、最後に発生したエラーの種類を確認できます。json_last_error_msg関数を使用すると、エラーメッセージを文字列で取得できます。

エラー検出の例

以下は、エンコードエラーの検出とエラーメッセージを表示する方法の例です。

$data = "\xB1\x31"; // 不正なUTF-8文字列

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

このコードは、以下のようなエラーメッセージを表示します。

JSONエンコードに失敗しました: Malformed UTF-8 characters, possibly incorrectly encoded

主なエラーの種類と対処法

json_last_error関数で取得できるエラーコードとその意味、対処法について解説します。

1. `JSON_ERROR_NONE`

• 意味: エラーは発生していません。
• 対処法: 特に対処は不要です。

2. `JSON_ERROR_DEPTH`

• 意味: 最大スタック深度を超えました。
• 対処法: 入れ子になった配列やオブジェクトの深さを減らし、デフォルトの深度（512）を超えないようにするか、json_encodeの第3引数で深度を設定します。

3. `JSON_ERROR_STATE_MISMATCH`

• 意味: 無効または不正なJSON。
• 対処法: 入力データを検証し、JSONとして正しい形式であるか確認します。

4. `JSON_ERROR_CTRL_CHAR`

• 意味: 不正な制御文字が含まれています。
• 対処法: データから制御文字を削除するか、エンコードする前にデータをクリーンアップします。

5. `JSON_ERROR_SYNTAX`

• 意味: JSONの構文エラー。
• 対処法: 入力データを再確認し、正しい構文に修正します。

6. `JSON_ERROR_UTF8`

• 意味: 不正なUTF-8文字が含まれています。
• 対処法: UTF-8エンコーディングを適用するか、mb_convert_encoding関数を使用して文字エンコーディングを修正します。

エンコードエラーの回避策

エラーを未然に防ぐためのいくつかの方法を紹介します。

UTF-8エンコードを適用する

エンコード前にデータをUTF-8に変換しておくことで、UTF-8エラーを回避できます。

$data = "こんにちは";
$data = mb_convert_encoding($data, 'UTF-8', 'auto');
$json = json_encode($data);

深度を調整する

深くネストされた配列を処理する場合、第3引数で深度を指定することでエラーを防ぐことができます。

$json = json_encode($data, 0, 1024); // 最大深度を1024に設定

エンコード時のエラーを適切に処理することで、PHPアプリケーションの信頼性を向上させ、エラーが発生しても柔軟に対処できるようになります。

json_encodeの応用例

PHPのjson_encode関数は、データをJSON形式に変換するための基本的なツールですが、様々な応用シナリオで活用することができます。以下では、実際のプロジェクトで役立つ応用例を紹介します。

1. Web APIのレスポンスを作成する

Web APIでは、サーバーからクライアントにデータを返す際にJSON形式を使用するのが一般的です。PHPでAPIを実装する場合、json_encodeを使ってレスポンスを生成します。

例：APIレスポンスの作成

以下のコードは、ユーザー情報を取得してJSON形式で返すAPIの例です。

header('Content-Type: application/json');

$user = array(
    "id" => 1,
    "name" => "Taro",
    "email" => "taro@example.com",
    "is_active" => true
);

echo json_encode($user, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

この例では、JSON形式のレスポンスが次のように整形され、クライアントに返されます。

{
    "id": 1,
    "name": "Taro",
    "email": "taro@example.com",
    "is_active": true
}

2. JavaScriptとのデータ交換

PHPからJavaScriptにデータを渡す際にもjson_encodeを利用します。例えば、サーバーサイドでデータを生成し、そのデータをクライアントサイドのJavaScriptで使用することが可能です。

例：PHPからJavaScriptへのデータ送信

PHPで生成したデータをJavaScriptに渡す場合、次のようにjson_encodeを使用します。

$data = array(
    "title" => "Hello, World!",
    "views" => 100,
    "is_published" => true
);
?>
<script type="text/javascript">
    var articleData = <?php echo json_encode($data, JSON_UNESCAPED_UNICODE); ?>;
    console.log(articleData.title); // "Hello, World!" と表示されます
</script>

このコードにより、PHPで生成されたデータがJavaScriptのオブジェクトとして使用可能になります。

3. 設定ファイルの生成と読み込み

アプリケーションの設定をJSON形式で保存し、読み込むことで設定ファイルとして利用することができます。これにより、設定の読み書きが容易になります。

例：設定ファイルの保存

以下のコードでは、設定情報をJSON形式でファイルに保存します。

$config = array(
    "site_name" => "My Website",
    "maintenance_mode" => false,
    "admin_email" => "admin@example.com"
);

file_put_contents('config.json', json_encode($config, JSON_PRETTY_PRINT));

保存されたconfig.jsonファイルは以下のような内容になります。

{
    "site_name": "My Website",
    "maintenance_mode": false,
    "admin_email": "admin@example.com"
}

4. データベースから取得したデータのエンコード

データベースから取得した複数のレコードをJSON形式でエンコードし、クライアントに返すのも一般的な使い方です。以下は、データベースからユーザー情報を取得してJSONとして返す例です。

例：データベースのデータをJSONに変換する

// 仮想のデータベースから取得したデータの例
$users = array(
    array("id" => 1, "name" => "Taro", "email" => "taro@example.com"),
    array("id" => 2, "name" => "Hanako", "email" => "hanako@example.com"),
    array("id" => 3, "name" => "Jiro", "email" => "jiro@example.com")
);

header('Content-Type: application/json');
echo json_encode($users, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

出力されるJSONは次のようになります。

[
    {
        "id": 1,
        "name": "Taro",
        "email": "taro@example.com"
    },
    {
        "id": 2,
        "name": "Hanako",
        "email": "hanako@example.com"
    },
    {
        "id": 3,
        "name": "Jiro",
        "email": "jiro@example.com"
    }
]

5. エラーレスポンスの生成

エラーが発生した場合に、エラーメッセージをJSON形式で返すのも一般的です。これにより、クライアント側でエラーを解析し、適切なエラーハンドリングを行うことができます。

例：エラーレスポンスの生成

$response = array(
    "status" => "error",
    "message" => "ユーザーが見つかりません"
);

header('Content-Type: application/json');
echo json_encode($response, JSON_UNESCAPED_UNICODE);

出力は以下の通りです。

{
    "status": "error",
    "message": "ユーザーが見つかりません"
}

これらの応用例を通じて、json_encodeの便利さを実感でき、実際の開発で役立てることができるでしょう。

演習問題

これまで学んだjson_encodeの使い方や応用例を実際に試して理解を深めるために、いくつかの演習問題を用意しました。以下の問題を解いて、PHPでのJSON操作に慣れていきましょう。

演習問題1: 配列をJSON形式に変換する

次のPHP配列をJSON形式に変換し、画面に出力してください。出力する際に、JSON_PRETTY_PRINTオプションを使用して見やすい形式に整形してください。

$products = array(
    array("id" => 101, "name" => "Laptop", "price" => 1500),
    array("id" => 102, "name" => "Mouse", "price" => 20),
    array("id" => 103, "name" => "Keyboard", "price" => 30)
);

期待される出力:

[
    {
        "id": 101,
        "name": "Laptop",
        "price": 1500
    },
    {
        "id": 102,
        "name": "Mouse",
        "price": 20
    },
    {
        "id": 103,
        "name": "Keyboard",
        "price": 30
    }
]

演習問題2: オブジェクトをJSON形式に変換する

次のクラスを作成し、そのオブジェクトをJSON形式に変換して出力してください。クラスのプロパティはpublicとして定義し、名前（name）と年齢（age）を持つものとします。

class Person {
    public $name;
    public $age;

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

$person = new Person("Taro", 25);

期待される出力:

{"name":"Taro","age":25}

演習問題3: UTF-8文字のエンコード

以下の配列をJSON形式に変換する際、UTF-8文字をエスケープしないようにしてください。

$data = array("message" => "こんにちは、世界！");

期待される出力:

{"message":"こんにちは、世界！"}

演習問題4: エラー処理を追加する

不正なUTF-8文字列をエンコードする際にエラーが発生することがあります。以下の文字列をエンコードしてみて、エラーが発生した場合はエラーメッセージを表示するようにしてください。

$data = "\xB1\x31";

期待される処理結果:

• JSONエンコードに失敗しました: Malformed UTF-8 characters, possibly incorrectly encoded と表示される。

演習問題5: Web APIのレスポンスを作成する

ユーザー情報をJSON形式で返すAPIレスポンスを作成してください。ユーザー情報には、ID、名前、メールアドレス、および有効ステータス（is_active）を含めます。

$user = array(
    "id" => 1,
    "name" => "Hanako",
    "email" => "hanako@example.com",
    "is_active" => true
);

期待される出力:

{
    "id": 1,
    "name": "Hanako",
    "email": "hanako@example.com",
    "is_active": true
}

これらの演習問題を通じて、PHPでのjson_encodeの使い方やエラーハンドリングを実践し、理解を深めましょう。

よくある質問

json_encodeを使用する際に、多くの開発者が直面する疑問や問題について、よくある質問とその解決策を紹介します。

1. JSONに変換したデータが空（`null`）になってしまうのはなぜですか？

JSONエンコードの結果がnullになってしまう場合、次のような原因が考えられます。

• 不正なUTF-8文字列が含まれている。
• json_encodeが失敗している。

解決策：json_last_error()関数を使ってエラーをチェックし、mb_convert_encodingなどでデータをUTF-8に変換してからエンコードすることを試してみてください。

$data = "不正な文字列\xB1\x31";
$json = json_encode($data);
if ($json === null) {
    echo "エラー: " . json_last_error_msg();
}

2. 数値が文字列としてエンコードされてしまうのはなぜですか？

PHPの配列やオブジェクト内の数値が文字列として扱われている場合、json_encodeによって文字列のままエンコードされることがあります。

解決策：JSON_NUMERIC_CHECKオプションを使用して、文字列として定義されている数値を数値としてエンコードします。

$data = array("price" => "1500");
$json = json_encode($data, JSON_NUMERIC_CHECK);

3. 日本語が`\u`エスケープされてしまうのはなぜですか？

デフォルトでは、json_encodeは日本語などの非ASCII文字をエスケープします。これにより、文字が\uエスケープシーケンスで表示されます。

解決策：JSON_UNESCAPED_UNICODEオプションを使用してエスケープを防ぎます。

$data = array("greeting" => "こんにちは");
$json = json_encode($data, JSON_UNESCAPED_UNICODE);

4. JSONエンコードで「最大スタック深度を超えました」と表示されるのはなぜですか？

これは、エンコードする配列やオブジェクトが深くネストされすぎている場合に発生するエラーです。

解決策：json_encodeの第3引数で最大深度を指定するか、ネストの深さを減らすようにデータ構造を調整してください。

$json = json_encode($deepArray, 0, 1024); // 深度を1024に設定

5. プライベートプロパティがJSONに含まれないのはなぜですか？

json_encodeは、オブジェクトのpublicプロパティのみをエンコードします。プライベートまたは保護されたプロパティは、デフォルトではエンコードされません。

解決策：JsonSerializableインターフェースを実装して、カスタムのエンコードロジックを定義します。

class Product implements JsonSerializable {
    private $name;
    private $price;

    public function __construct($name, $price) {
        $this->name = $name;
        $this->price = $price;
    }

    public function jsonSerialize() {
        return [
            'name' => $this->name,
            'price' => $this->price
        ];
    }
}

$product = new Product("Laptop", 1500);
$json_product = json_encode($product);

これらのよくある質問と解決策を参考にして、json_encodeの問題に対処し、より効果的にJSONを活用しましょう。

まとめ

本記事では、PHPでのjson_encode関数を使った文字列のJSON形式への変換方法について解説しました。JSONの基本的な概念から始め、PHPでの利用方法、オプション設定、エラー処理、さらには実践的な応用例までカバーしました。

json_encodeを活用することで、PHPアプリケーションにおけるデータの交換がスムーズになり、Web APIやフロントエンドとの通信が効率的に行えるようになります。適切なオプションの利用とエラー処理を行うことで、さらに信頼性の高いシステムを構築することが可能です。

今後、実際のプロジェクトでこれらの知識を活かし、PHPでのJSON操作に習熟していきましょう。