はじめに

過去にやっていた案件でLaravelでAPIを作成する時に、このAPIリソースを活用してきました。
というわけで、過去の経験を基にAPIリソースの基本的な使い方を個人的にまとめたので紹介します。
もしかしたらもっと良い方法があるかもしれませんので、何かありましたらコメントで教えていただけますと幸いです。

Lumenでも扱うことができるのは確認済みなのですが、生成コマンドが存在しないので少し苦労するかもしれません。

バージョン

Laravel 5.5 ~ 5.6
Lumen 5.8

ドキュメント

Eloquent: APIリソース 5.5 Laravel

※ Lumenの方には、ドキュメントはありませんでした。おそらくほぼ一緒と思われます。

使用方法

一つのモデルを返す場合

以下のコマンドでリソースファイルを生成

php artisan make:resource UserResource

コントローラなどで返したいモデルを取得し、UserResourceクラスの引数に取得したモデルを設定

$user = User::find(1);
return new UserResource($user);

UserResourceクラスのtoArray()関数で設計しているAPIの通りに、レスポンスパラメータを設定する。

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

レスポンス

{
    "data": {
        "id": 1,
        "name": "hoge",
        "email": "hoge@example.com"
    }
}

複数のモデルを返す場合

UserResourceクラスのcollection()メソッドに取得した複数のモデルコレクションを設定

$users = User::all();
return UserResource::collection($users);

レスポンス

{
    "data": [
        {
            "id": 1,
            "name": "hoge",
            "email": "hoge@example.com"
        },
        {
            "id": 2,
            "name": "fuga",
            "email": "fuga@example.com"
        },
        {
            "id": 3,
            "name": "piyo",
            "email": "piyo@example.com"
        }
    ]
}

複数のモデルを返す場合に、レスポンスパラメータをカスタマイズしたい場合

以下のコマンドでコレクションリソースファイルを生成

php artisan make:resource UserCollection

コントローラで返したい複数のモデルを取得し、UserCollectionクラスの引数に取得したモデルを設定

$users = User::all();
return new UserCollection($users);

UserCollectionクラスのtoArray()関数で設計しているAPIの通りに、レスポンスパラメータを設定

public function toArray($request)
{
    return [
        'code'  => 200,
        'users' => UserResource::collection($this->collection),
    ];
}

レスポンス

{
    "code": 200,
    "data": [
        {
            "id": 1,
            "name": "hoge",
            "email": "hoge@example.com"
        },
        {
            "id": 2,
            "name": "fuga",
            "email": "fuga@example.com"
        },
        {
            "id": 3,
            "name": "piyo",
            "email": "piyo@example.com"
        }
    ]
}

リソースファイル、コレクションリソースファイルにモデル以外の情報を引数に含めたい場合

UserResourceまたはUserCollectionの中で__construct()を設定することで、モデル以外の情報を引数に含めることができる。
※ collection()メソッドを使う場合は、このやり方は使えない。

return new UserResource($users, $post);

// or

return new UserCollection($users, $post);

public function toArray($request)
{
    return [
        'id'      => $this->id,
        'name'    => $this->name,
        'email'   => $this->email,
        'post_id' => $this->post->id,
    ];
}

/**
 * Create a new resource instance.
 *
 * @param  mixed  $resource
 * @return void
 */
public function __construct($resource, $post)
{
    $this->resource = $resource;
    $this->post = $post;
}

レスポンス

{
    "data": {
        "id": 1,
        "name": "hoge",
        "email": "hoge@example.com",
        "post_id": 1
    }
}