【PHP8.x】JsonSerializable::jsonSerialize()メソッドの使い方

jsonSerializeメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2026年02月12日

基本的な使い方

jsonSerializeメソッドは、PHPのオブジェクトをJSON（JavaScript Object Notation）形式に変換する際に、そのオブジェクトがどのように表現されるべきかを定義するために使用されるメソッドです。

このメソッドは、JsonSerializableというインターフェースに定義されており、このインターフェースを実装するクラスが、自身のオブジェクトをJSON形式でシリアライズする際の挙動をカスタマイズするために用います。具体的には、PHPの組み込み関数であるjson_encode()を使ってオブジェクトをJSONに変換しようとした際、もしそのオブジェクトがJsonSerializableインターフェースを実装していれば、json_encode()はオブジェクトのデフォルトのプロパティをそのままJSONにするのではなく、代わりにこのjsonSerialize()メソッドを自動的に呼び出します。

jsonSerialize()メソッドは、最終的にJSONとして出力したいデータを配列やオブジェクトなど、json_encode()関数が処理できる形式で返す必要があります。この戻り値が、json_encode()によってJSON文字列へと変換される対象となります。この機能の最大の利点は、オブジェクトの内部構造をそのまま公開するのではなく、外部に公開したいデータだけを選んだり、クラスの内部で計算された値をJSONに含めたりするなど、JSONの出力内容を柔軟に制御できる点です。例えば、セキュリティ上公開すべきでないプライベートなプロパティを除外したり、APIのレスポンスとして特定のフォーマットに整形したデータを返したりする際に非常に有用です。これにより、オブジェクトの内部実装と外部へのデータ公開形式を分離し、意図した通りの、構造化されたJSONデータを効率的に生成することが可能になります。

構文(syntax)


1<?php
2
3class MyData implements JsonSerializable
4{
5    public function jsonSerialize(): mixed
6    {
7    }
8}

引数(parameters)

引数なし

引数はありません

戻り値(return)

mixed

jsonSerialize メソッドは、オブジェクトをJSON形式で表現できるデータ（配列やスカラー値など）を返します。これにより、オブジェクトのJSONエンコード時の振る舞いをカスタマイズできます。

サンプルコード

PHP JsonSerializableでオブジェクトをJSON化する


1<?php
2
3/**
4 * JsonSerializableインターフェースを実装するクラスの例。
5 * このインターフェースを実装することで、オブジェクトがjson_encode()関数で
6 * JSON文字列に変換される際に、どのようにデータがシリアライズされるかを制御できます。
7 */
8class UserProfile implements JsonSerializable
9{
10    private int $id;
11    private string $name;
12    private string $email;
13    private bool $isActive;
14
15    /**
16     * コンストラクタでプロパティを初期化します。
17     */
18    public function __construct(int $id, string $name, string $email, bool $isActive)
19    {
20        $this->id = $id;
21        $this->name = $name;
22        $this->email = $email;
23        $this->isActive = $isActive;
24    }
25
26    /**
27     * オブジェクトがjson_encode()によってJSONにシリアライズされる際に呼び出されます。
28     * このメソッドは、JSONとして表現されるべきデータを返します。
29     * 通常は連想配列（JSONオブジェクト）またはインデックス配列（JSON配列）を返します。
30     *
31     * @return mixed シリアライズされるデータ。
32     */
33    public function jsonSerialize(): mixed
34    {
35        // オブジェクトのプライベートプロパティを、JSONに適した連想配列として返します。
36        // ここで返される配列のキーがJSONのキーになります。
37        return [
38            'userId' => $this->id,
39            'userName' => $this->name,
40            'userEmail' => $this->email,
41            'status' => $this->isActive ? 'active' : 'inactive' // 論理値を文字列に変換して出力することも可能
42        ];
43    }
44}
45
46// UserProfileクラスのインスタンスを作成します。
47$user = new UserProfile(101, "山田 太郎", "taro.yamada@example.com", true);
48
49// json_encode()関数を使用してオブジェクトをJSON文字列に変換します。
50// UserProfileクラスがJsonSerializableを実装しているため、jsonSerialize()メソッドが呼び出され、
51// その戻り値がJSONとしてエンコードされます。
52// JSON_PRETTY_PRINTは、出力を見やすくするためのオプションです。
53$jsonOutput = json_encode($user, JSON_PRETTY_PRINT);
54
55// 生成されたJSON文字列を出力します。
56echo $jsonOutput;
57

PHP 8におけるJsonSerializableインターフェースは、オブジェクトをJSON形式に変換する際の動作を制御するために使用されます。このインターフェースをクラスに実装すると、json_encode()関数でそのオブジェクトがJSON文字列に変換される際に、自動的にjsonSerialize()メソッドが呼び出されるようになります。

jsonSerialize()メソッドは引数を持ちませんが、オブジェクトのプロパティからJSONとして表現したいデータを構築し、そのデータを戻り値として返します。戻り値の型はmixedで、通常は連想配列（JSONオブジェクト）やインデックス配列（JSON配列）を返します。これにより、プライベートなプロパティや計算された値をJSONとして公開するデータを細かく制御できます。

サンプルコードでは、UserProfileクラスがJsonSerializableインターフェースを実装しています。jsonSerialize()メソッド内では、ユーザーのIDや名前、メールアドレスといったプライベートなプロパティを、JSONのキーと値に対応する連想配列として組み立てて返しています。例えば、isActiveという真偽値は、JSONでは'active'または'inactive'という文字列に変換されて出力されます。

このように、JsonSerializableとjsonSerialize()メソッドを利用することで、オブジェクトの内部構造を直接JSONとして公開するのではなく、必要な情報だけを整形して安全かつ柔軟にJSONデータを作成できるため、API開発などで非常に有用です。

このサンプルコードは、オブジェクトをJSONに変換する際、jsonSerializeメソッドを使って出力データを細かく制御できる仕組みを示しています。初心者の方は、このメソッドが返す配列や値が直接JSONの形式になる点を理解することが重要です。例えば、privateなプロパティも、必要に応じて加工して出力できますが、パスワードなどの機密情報は決してJSONに含めないよう細心の注意を払いましょう。また、jsonSerializeメソッドの戻り値は通常、連想配列やインデックス配列、またはプリミティブな値であるべきです。循環参照を引き起こすようなオブジェクトを返すと、json_encodeがエラーになる可能性があるため、予期せぬ挙動を防ぐためにも、常にjson_encodeの戻り値をチェックし、エラーハンドリングを行う習慣をつけることをお勧めします。