README

Adds extra functionality to the Laravel Eloquent: API Resources, allowing you to choose attributes and relationships to return via url

Introduction

When we create a JSON API from Laravel we can do it in many ways, the most used way (I think) is to create a Rest API. We can use the json:api specification if we want or use one of the great libraries already available for Laravel such as:

• Laravel Orion
• Laravel Restify
• Laravel JSON:API

But it is possible that our API with the standard methods of a Rest API is not enough and we prefer to have extra parameters with which to perform different queries on the data before returning it in JSON format.
In this case we can generate our queries with Eloquent and return the data with the toJson method.
With the use of the Laravel Eloquent: API Resources we can control which attributes and relationships we want to return for each model in a static way. With this small library that we have here we can modify the API Resources dynamically from parameters in the url.

Instalation

Install using Composer

composer require emeguan/laravel-resources

Requirements

I have not tested it but it should work with any version of Laravel that includes Eloquent API Resources, that is, Laravel 5.5 and later.
The code has been tested with Laravel 9

Use

Model

class A extends Model
{
    use HasFactory;
    use \EmeGuan\Resources\ModelTrait;  //<--

Controller

Route::get('/as', function ()
{
    $as=A::all();
    return new \EmeGuan\Resources\Collection($as);
});

Route::get('/a/{id}', function ($id)
{
    $a=A::find($id);
    return new \EmeGuan\Resources\Resource($a);  //<--
});

Call

http://laravel-resource.local/as

{
  "data": [
    {
      "id": 1,
      "name": "A1",
      "created_at": "2023-02-06 16:55:52",
      "updated_at": "2023-02-06 16:55:52"
    },
    {
      "id": 2,
      "name": "A2",
      "created_at": "2023-02-06 16:55:52",
      "updated_at": "2023-02-06 16:55:52"
    },

http://laravel-resource.local/a/1

{
  "data": {
    "id": 1,
    "name": "A1",
    "created_at": "2023-02-06 16:55:52",
    "updated_at": "2023-02-06 16:55:52"
  }
}

Documentation

In the url we can specify the attributes we want from a model and the relationships to include. Let's see this with an example.
We start from these 5 models:

class A extends Model
{
    use HasFactory;
    use ModelTrait;

    protected $fillable = [ 'id', 'name'];

    public function bs()
    {
        return $this->hasMany(B::class);
    }
    
    public function ds()
    {
        return $this->hasMany(D::class);
    }
}

class B extends Model
{
    use HasFactory;
    use ModelTrait;

    protected $fillable = [ 'id', 'name', 'a_id'];

    public function cs()
    {
        return $this->hasMany(C::class);
    }

    public function a()
    {
        return $this->belongsTo(A::class);
    }
}

class C extends Model
{
    use HasFactory;
    use ModelTrait;

    protected $fillable = [ 'id', 'name', 'b_id'];

    public function b()
    {
        return $this->belongsTo(B::class);
    }
}

class D extends Model
{
    use HasFactory;
    use ModelTrait;

    protected $fillable = [ 'id', 'name', 'a_id'];

    public function es()
    {
        return $this->hasMany(E::class);
    }

    public function a()
    {
        return $this->belongsTo(A::class);
    }
}

class E extends Model
{
    use HasFactory;
    use ModelTrait;

    protected $fillable = [ 'id', 'name', 'd_id'];

    public function d()
    {
        return $this->belongsTo(D::class);
    }
}

• Get all As with onlly id and name attribute
  http://laravel-resources.local/as?fields[as]=id,name

{
  "data": [
    {
      "id": 1,
      "name": "A1"
    },
    {
      "id": 2,
      "name": "A2"
    },
    {
      "id": 3,
      "name": "A3"
    },

• Get all As include all Bs with specific attributes
  http://laravel-resources.local/as?include=bs&fields[as]=id,name&fields[bs]=name

{
  "data": [
    {
      "id": 1,
      "name": "A1",
      "bs": [
        {
          "name": "B1"
        },
        {
          "name": "B2"
        },
        {
          "name": "B3"
        }
      ]
    },
    {
      "id": 2,
      "name": "A2",
      "bs": [
        {
          "name": "B4"
        },
        {
          "name": "B5"
        },
        {
          "name": "B6"
        }
      ]
    },
    {
      "id": 3,
      "name": "A3",
      "bs": [
        {
          "name": "B7"
        },
        {
          "name": "B8"
        }
      ]
    },

• We can include multilevel relationships with the dot notation.
  http://laravel-resources.local/as?include=bs.cs&fields[as]=id,name&fields[bs]=name

{
  "data": [
    {
      "id": 1,
      "name": "A1",
      "bs": [
        {
          "name": "B1",
          "cs": [
            {
              "id": 1,
              "name": "C1",
              "b_id": 1,
              "created_at": "2023-02-06 16:57:18",
              "updated_at": "2023-02-06 16:57:18"
            },
            {
              "id": 2,
              "name": "C2",
              "b_id": 1,
              "created_at": "2023-02-06 16:57:18",
              "updated_at": "2023-02-06 16:57:18"
            },
            {
              "id": 3,
              "name": "C3",
              "b_id": 1,
              "created_at": "2023-02-06 16:57:18",
              "updated_at": "2023-02-06 16:57:18"
            }
          ]
        },
        {
          "name": "B2",
          "cs": [
            {
              "id": 4,
              "name": "C4",
              "b_id": 2,
              "created_at": "2023-02-06 16:57:18",
              "updated_at": "2023-02-06 16:57:18"
            },
            {
              "id": 5,
              "name": "C5",
              "b_id": 2,
              "created_at": "2023-02-06 16:57:18",
              "updated_at": "2023-02-06 16:57:18"
            },
            {
              "id": 6,
              "name": "C6",
              "b_id": 2,
              "created_at": "2023-02-06 16:57:18",
              "updated_at": "2023-02-06 16:57:18"
            }
          ]
        },
        {
          "name": "B3",
          "cs": [
            {
              "id": 7,
              "name": "C7",
              "b_id": 3,
              "created_at": "2023-02-06 16:57:18",
              "updated_at": "2023-02-06 16:57:18"
            },
            {
              "id": 8,
              "name": "C8",
              "b_id": 3,
              "created_at": "2023-02-06 16:57:18",
              "updated_at": "2023-02-06 16:57:18"
            }
          ]
        }
      ]
    },
    {
      "id": 2,
      "name": "A2",
      "bs": [

If attributes are not specified all are returned.
All relations are included with the dot notation, in the example it is not necessary to specify include=bs,bs.cs

• We can include belongsTo relationships
  http://laravel-resources.local/bs?fields[bs]=name,a&fields[a]=id,name

{
  "data": [
    {
      "name": "B1",
      "a": {
        "id": 1,
        "name": "A1"
      }
    },
    {
      "name": "B2",
      "a": {
        "id": 1,
        "name": "A1"
      }
    },
    {
      "name": "B3",
      "a": {
        "id": 1,
        "name": "A1"
      }
    },

• If you need all the attributes and some relationship you can use * to replace all the attributes
  http://laravel-resources.local/bs?fields[bs]=*,a&fields[a]=id,name

{
  "data": [
    {
      "id": 1,
      "name": "B1",
      "a": {
        "id": 1,
        "name": "A1"
      }
    },
    {
      "id": 2,
      "name": "B2",
      "a": {
        "id": 1,
        "name": "A1"
      }
    },
    {
      "id": 3,
      "name": "B3",
      "a": {
        "id": 1,
        "name": "A1"
      }
    },

• We can include multiple relationships separated by commas
  http://laravel-resources.local/as?include=bs,ds&fields[bs]=name&fields[ds]=name

{
  "data": [
    {
      "id": 1,
      "name": "A1",
      "created_at": "2023-02-06 16:55:52",
      "updated_at": "2023-02-06 16:55:52",
      "bs": [
        {
          "name": "B1"
        },
        {
          "name": "B2"
        },
        {
          "name": "B3"
        }
      ],
      "ds": [
        {
          "name": "D1"
        },
        {
          "name": "D2"
        },
        {
          "name": "D3"
        }
      ]
    },
    {
      "id": 2,
      "name": "A2",
      "created_at": "2023-02-06 16:55:52",
      "updated_at": "2023-02-06 16:55:52",
      "bs": [
        {
          "name": "B4"
        },
        {
          "name": "B5"
        },
        {
          "name": "B6"
        }
      ],
      "ds": [
        {
          "name": "D4"
        },
        {
          "name": "D5"
        },
        {
          "name": "D6"
        }
      ]
    },

• You may need to create several methods that return the same collection but with different functionality. There is no problem since the name of the main relation is taken from the name of the model collection table.
  http://laravel-resources.local/as-call-1?fields[as]=id,name

{
  "data": [
    {
      "id": 1,
      "name": "A1"
    },
    {
      "id": 2,
      "name": "A2"
    },
    {
      "id": 3,
      "name": "A3"
    },
    {
      "id": 4,
      "name": "A4"
    },
    {
      "id": 5,
      "name": "A5"
    },

TODO

• When we include a second level relationship and the first level does not specify any attribute with fields[relationship]= an output similar to this is returned
  http://laravel-resources.local/as?include=bs.cs&fields[as]=id&fields[bs]=&fields[cs]=name

{
  "data": [
    {
      "id": 1,
      "bs": [
        {
          "cs": [
            {
              "name": "C1"
            },
            {
              "name": "C2"
            },
            {
              "name": "C3"
            }
          ]
        },
        {
          "cs": [
            {
              "name": "C4"
            },
            {
              "name": "C5"
            },
            {
              "name": "C6"
            }
          ]
        },
        {
          "cs": [
            {
              "name": "C7"
            },
            {
              "name": "C8"
            }
          ]
        }
      ]
    },

Something similar to this could be returned where the 1st level relationship did not appear

{
  "data": [
    {
      "id": 1,
      "cs": [
        {
          "name": "C1"
        },
        {
          "name": "C2"
        },
        {
          "name": "C3"
        },
        {
          "name": "C4"
        },
        {
          "name": "C5"
        },
        {
          "name": "C6"
        },
        {
          "name": "C7"
        },
        {
          "name": "C8"
        }
      ]
    },

• ...

License

Laravel API Resources is open-source software licensed under the MIT license.