【Laravel】API Resourceでレスポンスを整形する方法

Q: 単一リソースとコレクションでクラスを分ける必要はありますか？

基本は単一リソースクラスだけで十分です。 コレクション全体にメタ情報や集計値を足したいときだけ、make:resource --collection でResourceCollectionクラスを作ります。

Q: 特定の項目を条件によって出したり隠したりできますか？

when メソッドが使えます。 'is_admin' => $this->when($request->user()?->isAdmin(), true) のように書くと、条件がtrueのときだけキーを含められます。

2026年8月30日

いずみ

当ページのリンクには広告が含まれています。

この記事で解決できる悩み

LaravelのAPI Resourceでレスポンスを整形する方法は？

いずみ

こんな悩みを解決できる記事を書きました！

僕は現役フリーランスエンジニア（歴10年）で、資格は13個保有しています。

「LaravelのAPIで、モデルの中身をそのまま返すのをやめて、必要な項目だけを整形して返したい」とお考えではありませんか？

Eloquentモデルをそのままreturnすると、内部用のカラムまでJSONに含まれてしまいます。

API Resourceを使うと、モデルとレスポンスの間に変換レイヤーを1枚はさめます。

返す項目・キー名・リレーションの出し方をクラス1つにまとめられるので、APIの構造が安定します。

いずみ

レスポンス整形はコントローラーに書きがちですが、Resourceに寄せると一気に読みやすくなります。

ということで、本記事ではLaravelのAPI Resourceでレスポンスを整形する方法を解説します。

いずみ

すぐ読み終わるので、ぜひ最後まで読んでくださいませ。

スクロールできます

【当サイト】おすすめフリーランスエージェント3選
エージェント	評価	ポイント	公式サイト
レバテックフリーランス	5.0	業界最大級のエージェント。高単価案件が豊富。	公式
Midworks	4.8	満足度調査で 3年連続3冠を達成。	公式
ITプロパートナーズ	4.6	週2〜3向けの案件が豊富。	公式

執筆者／監修者

フリーランスエンジニア（保有資格13個、企業と直接契約）
ブログ・アフィリエイト歴7年（2018年〜）
ブランドせどりで月利50万円⇨脱サラ
投資（仮想通貨・FX）歴7年（2018年〜）
X（旧Twitter）フォロワー約1,900人
運営者情報はこちら

いずみです

よく読まれている記事はこちら！

【Laravel】API Resourceでレスポンスを整形する方法

早速、LaravelのAPI Resourceでレスポンスを整形する手順を見ていきます。

API Resourceの役割

API Resourceは、Illuminate\Http\Resources\Json\JsonResource を継承したクラスです。

1件のモデルを表すリソースクラスと、複数件を表すリソースコレクションの2種類があります。

toArray メソッドの戻り値が、そのままJSONのレスポンスボディになります。

いずみ

モデルの属性を「APIとして見せたい形」に翻訳する係、とイメージすると分かりやすいです。

リソースクラスを作成する

リソースクラスの生成から、コントローラーで返すところまでを順に進めます。

STEP

make:resourceコマンドでリソースクラスを生成する

php artisan make:resource UserResource

生成されたクラスは app/Http/Resources ディレクトリに置かれます。

STEP

toArrayメソッドで返す項目を定義する

public function toArray($request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'registered_at' => $this->created_at->toDateString(),
    ];
}

配列のキーが、そのままレスポンスのキー名になります。

created_at をフォーマットし直すといった整形処理も、toArray の中で完結できます。

STEP

コントローラーでリソースを返す

use App\Http\Resources\UserResource;

public function show(User $user)
{
    return new UserResource($user);
}

public function index()
{
    return UserResource::collection(User::paginate(15));
}

1件返すときは new UserResource、一覧を返すときは UserResource::collection を使います。

いずみ

collectionにpaginateの結果を渡すと、links と meta のページネーション情報が自動で付きます。

リレーションを条件付きで含める

リレーションを常にロードすると、不要なときでもクエリが増えます。

whenLoaded メソッドを使うと、ロード済みのリレーションだけをレスポンスに含められます。

public function toArray($request): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'posts' => PostResource::collection($this->whenLoaded('posts')),
    ];
}

コントローラー側で User::with('posts') を呼んだときだけ、posts キーが出力されます。

リレーションが未ロードのときは、posts キー自体がレスポンスから消えます。

いずみ

whenLoadedはN+1対策とセットで覚えておくと便利です。

メタ情報やラッピングを調整する

additional メソッドで、レスポンスに任意の付加情報を足せます。

return (new UserResource($user))->additional([
    'meta' => ['version' => 'v1'],
]);

デフォルトでは、レスポンス全体が data キーでラップされます。

data キーを外したい場合は、AppServiceProvider の boot で JsonResource::withoutWrapping() を呼びます。

use Illuminate\Http\Resources\Json\JsonResource;

public function boot(): void
{
    JsonResource::withoutWrapping();
}

いずみ

フロント側の実装に合わせて、dataラップの有無を最初に決めておくと後がラクです。

スクロールできます

【当サイト】おすすめフリーランスエージェント3選
エージェント	評価	ポイント	公式サイト
レバテックフリーランス	5.0	業界最大級のエージェント。高単価案件が豊富。	公式
Midworks	4.8	満足度調査で 3年連続3冠を達成。	公式
ITプロパートナーズ	4.6	週2〜3向けの案件が豊富。	公式

【厳選】フリーランスエンジニアにおすすめなエージェント3選

フリーランスエンジニアになるにはエージェントから案件をもらう必要があります。

僕が実際に利用しているおすすめエージェントを紹介しますね。

いずみ

エージェントは必ず複数登録してください。

担当者によっては「全然案件紹介してくれない…」みたいなこともあるので…

僕は実際に5つのエージェントを使い回していますよ。

フリーランスを始めるなら「レバテックフリーランス」

案件数	マージン率	単価
約88,000件	非公開	高
初心者	福利厚生	申し込み
		無料

Good Point

業界最大級の案件数。
業界トップクラスの高単価報酬、低マージン（平均年収862万円）。
案件参画中のフォローの充実。

※詳細は「【業界最大手】レバテックフリーランスとは？メリットや利用手順を解説！」を参照。

レバテックフリーランス は業界最大手のフリーランスエージェントです。

とにかく案件数が多いので、とりあえず登録しておけば間違いないエージェントです！

いずみ

僕もはじめてフリーランスの案件を貰ったのはレバテックフリーランス です。

保有している案件数が多いので、業務経験がなくても何かしらの案件は紹介してもらえますよ（僕はJavaの経験3年でも案件を貰えました）。

詳細はコチラ

公式サイトを詳しく見る

手厚い保障を重視したいなら「Midworks 」

案件数	マージン率	単価
約10,000件	非公開	中
初心者	福利厚生	申し込み
		無料

Good Point

手厚い保障で正社員並みの安心感。
還元率60％超え＆単価公開でクリアな契約。
給与保障制度（審査あり）。

Midworks は手厚い保障が特徴のフリーランスエージェントです。

フリーランスを目指しているけど不安な方や保障を重視したい方におすすめです。

いずみ

僕も何度か案件を紹介してもらいました。

自分のスキルに合った案件を紹介してもらえましたし、電話のやり取りも非常に丁寧でした。

詳細はコチラ

公式サイトを詳しく見る

週2〜3日の案件探しなら「ITプロパートナーズ」

案件数	マージン率	単価
約5,000件	非公開	高
初心者	福利厚生	申し込み
経験者向け		無料

Good Point

IT案件に特化したフリーランスエージェント。
週2〜3日の案件が豊富。
リモート案件が多く、直エンドなので単価も高い。

※詳細は「【週2・3案件】ITプロパートナーズとは？メリットや利用手順を解説！」を参照。

ITプロパートナーズ はIT案件に特化したフリーランスエージェントです。

週2〜3日から参画できる案件が豊富なので、起業したい人にもおすすめです。

いずみ

週2〜3日の案件はある程度スキルがないと紹介してもらえない印象です。

とはいえ、週5の案件ももちろんありますし、僕が利用した時は迅速・丁寧に対応していただきました！

詳細はコチラ

公式サイトを詳しく見る

よくある質問

単一リソースとコレクションでクラスを分ける必要はありますか？

基本は単一リソースクラスだけで十分です。

コレクション全体にメタ情報や集計値を足したいときだけ、make:resource --collection でResourceCollectionクラスを作ります。

特定の項目を条件によって出したり隠したりできますか？

when メソッドが使えます。

'is_admin' => $this->when($request->user()?->isAdmin(), true) のように書くと、条件がtrueのときだけキーを含められます。

API Resourceと外部の整形ライブラリの違いは何ですか？

API ResourceはLaravel標準機能なので、追加インストールが不要です。

JSON:API仕様に厳密に沿いたい場合は専用パッケージを検討しますが、多くのAPIは標準のAPI Resourceで足ります。

まとめ

今回は、LaravelのAPI Resourceでレスポンスを整形する方法について解説しました。

以下が本記事のまとめになります。

まとめ

API Resourceはモデルとレスポンスの間の変換レイヤーで、返す項目をtoArray にまとめられる。
1件は new UserResource、一覧は UserResource::collection で返し、paginateならページネーション情報も自動で付く。
whenLoaded でロード済みリレーションだけを含め、additional や withoutWrapping でメタ情報とラッピングを調整できる。

まとめ

おすすめ本

PHPフレームワーク Laravel入門第2版

¥2,673 （2023/07/23 15:53時点 | Amazon調べ）

Amazon

＼楽天ポイント4倍セール！／

楽天市場

ポチップ

Laravelの勉強なら「PHPフレームワーク Laravel入門第2版」が分かりやすくておすすめですよ♪

いずみ

最後までお読みいただき、ありがとうございました！

スクロールできます

【当サイト】おすすめフリーランスエージェント3選
エージェント	評価	ポイント	公式サイト
レバテックフリーランス	5.0	業界最大級のエージェント。高単価案件が豊富。	公式
Midworks	4.8	満足度調査で 3年連続3冠を達成。	公式
ITプロパートナーズ	4.6	週2〜3向けの案件が豊富。	公式