本文へ移動
Laravel Tips

配列や JSON に変換する

モデルやコレクションを配列や JSON に変える方法と、パスワードなどを隠す設定、追加の値の足し方、日付の形の変え方を説明します。

API（ほかのプログラムにデータを渡す窓口）を作るとき、モデルやリレーションを、配列や JSON（データを文字で表す形式）に変えたいことがよくあります。この「変える」ことを、シリアライズと言います。Eloquent には、この変換をするメソッドと、変換後の形に入れる属性（カラムの値）を決めるしくみがあります。

補足

モデルやコレクションを JSON にする、もっとしっかりした方法として、API リソースがあります。

モデルとコレクションを変える#

配列に変える#

モデルと、読み込み済みのリレーション（表どうしのつながり）を配列に変えるには、toArray を使います。このメソッドは再帰的（中の中まで順に処理）なので、全部の属性と全部のリレーション（リレーションのリレーションも）が配列になります。

php
use App\Models\User;

$user = User::with('roles')->first();

return $user->toArray();

attributesToArray は、モデルの属性だけを配列にします。リレーションは入りません。

php
$user = User::first();

return $user->attributesToArray();

モデルのコレクション全体も、コレクションの toArray で、配列にできます。

php
$users = User::all();

return $users->toArray();

JSON に変える#

モデルを JSON に変えるには、toJson を使います。toArray と同じく再帰的なので、全部の属性とリレーションが JSON になります。PHP が対応している JSON の変換オプションも渡せます。

php
use App\Models\User;

$user = User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

モデルやコレクションを文字列にキャスト（型を変えること）しても、自動で toJson が呼ばれます。

php
return (string) User::find(1);

文字列にすると JSON になるので、アプリのルートやコントローラーから、Eloquent のオブジェクトを、そのまま返せます。Laravel が、自動で JSON に変えます。

php
Route::get('/users', function () {
    return User::all();
});
メソッド 働き
toArray 属性とリレーションを、配列にする
attributesToArray 属性だけを、配列にする
toJson 属性とリレーションを、JSON にする

リレーションの名前#

モデルを JSON にすると、読み込み済みのリレーションも、JSON の属性として自動で入ります。また、リレーションのメソッドの名前は「キャメルケース」（postComments のように単語をつなげる書き方）で書きますが、JSON の属性の名前は「スネークケース」（post_comments のように _ でつなぐ書き方）になります。

JSON から属性を隠す#

パスワードなど、配列や JSON に入れたくない属性があることがあります。モデルに Hidden 属性（PHP の属性。クラスの前に書く印）を付けます。Hidden に書いた属性は、モデルを変換した結果に入りません。

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Model;

#[Hidden(['password'])]
class User extends Model
{
    // ...
}

補足

リレーションを隠すには、モデルの Hidden 属性に、そのリレーションのメソッドの名前を足します。

反対に、Visible 属性で、入れてよい属性の「許可リスト」を決めることもできます。Visible にない属性は、配列や JSON に変えるとき、全部隠れます。

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Visible;
use Illuminate\Database\Eloquent\Model;

#[Visible(['first_name', 'last_name'])]
class User extends Model
{
    // ...
}

見える・隠れるを一時的に変える#

ふだんは隠れている属性を、あるモデルだけ見えるようにしたいときは、makeVisible か mergeVisible を使います。makeVisible は、モデルを返します。

php
return $user->makeVisible('attribute')->toArray();

return $user->mergeVisible(['name', 'email'])->toArray();

同じように、ふだんは見える属性を隠したいときは、makeHidden か mergeHidden を使います。

php
return $user->makeHidden('attribute')->toArray();

return $user->mergeHidden(['name', 'email'])->toArray();

見える属性や隠す属性を、全部、一時的に置き換えたいときは、setVisible と setHidden を使います。

php
return $user->setVisible(['id', 'name'])->toArray();

return $user->setHidden(['email', 'password', 'remember_token'])->toArray();
メソッド 働き
makeVisible 隠れている属性を、見えるようにする
mergeVisible いま見える属性は残して、見える属性を足す
makeHidden 見える属性を、隠す
mergeHidden いま隠れている属性は残して、隠す属性を足す
setVisible 見える属性を、全部置き換える
setHidden 隠す属性を、全部置き換える

JSON に値を足す#

モデルを配列や JSON に変えるとき、データベースにカラムがない属性を足したいことがあります。まず、その値のアクセサ（属性を読むときに値を加工する仕組み）を書きます。

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Determine if the user is an administrator.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

このアクセサを、いつもモデルの配列や JSON に足したいときは、モデルに Appends 属性を付けます。アクセサのメソッドの名前はキャメルケースですが、Appends に書く名前は、ふつう、配列や JSON に出るときの形（スネークケース）にします。

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Appends;
use Illuminate\Database\Eloquent\Model;

#[Appends(['is_admin'])]
class User extends Model
{
    // ...
}

appends のリストに足した属性は、モデルの配列と JSON の両方に入ります。また、appends にある属性も、モデルの visible と hidden の設定に従います。

実行中に足す#

プログラムの途中で、1つのモデルにだけ足す属性を決めたいときは、append か mergeAppends を使います。setAppends は、そのモデルの足す属性の配列を、全部置き換えます。

php
return $user->append('is_admin')->toArray();

return $user->mergeAppends(['is_admin', 'status'])->toArray();

return $user->setAppends(['is_admin'])->toArray();

同じように、モデルの、足す属性を全部取り除きたいときは、withoutAppends を使います。

php
return $user->withoutAppends()->toArray();
メソッド 働き
append 足す属性を足す
mergeAppends いまの足す属性は残して、足す属性を足す
setAppends 足す属性を、全部置き換える
withoutAppends 足す属性を、全部取り除く

日付の変換#

日付の形を全体で変える#

日付を配列や JSON に変えるときの、既定の形は、serializeDate を書き換えて変えられます。この設定は、データベースに保存するときの日付の形には、影響しません。

php
/**
 * Prepare a date for array / JSON serialization.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

日付の形を属性ごとに変える#

Eloquent の日付の属性ごとに、変換の形を変えるには、モデルのキャストの宣言に、日付の形を書きます。

php
protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}

関連するページ#

公式ドキュメント（英語）

2026年10月5日時点の内容をもとに、日本語でまとめています。

ページの一覧