WhenLoaded helpers

This package also provides another little trait that might be helpful. Add the HasRelationships trait to your API resources to make use of the makeWhenLoaded() and collectionWhenLoaded() methods. These methods merge a relationship into your API resource when the given relationship is loaded on the model. This may be helpful since you can define all relationships in your API resource and manage the relationships should be loaded from the controller. Let us show you some example resources:

use AgilePixels\ResourceAbilities\HasRelationships;
use AgilePixels\ResourceAbilities\JsonResource\ProcessesAbilities;

class PostResource extends JsonResource
{
    use ProcessesAbilities, HasRelationships;

    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'slug' => $this->slug,
            'published_at' => $this->published_at,

            'author' => UserResource::makeWhenLoaded('author', $this),

            'abilities' => $this->abilities(PostPolicy::class)
        ];
    }
}

use AgilePixels\ResourceAbilities\HasRelationships;
use AgilePixels\ResourceAbilities\JsonResource\ProcessesAbilities;

class UserResource extends JsonResource
{
    use ProcessesAbilities, HasRelationships;
    
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
    
            'posts' => PostResource::collectionWhenLoaded('posts', $this),
    
            'abilities' => $this->abilities(UserPolicy::class)
        ];
    }
}

Including a nested to-one relationship

Now, when returning a list of posts, the author won't be added to the PostResource response.

public function index()
{
    return
        PostResource::collection(
            Post::query()->get()
        )
    ;
}

{
    "data": [
        {
            "id": 1,
            "title": "Perspiciatis veritatis rerum voluptatem reprehenderit earum rerum quod.",
            "slug": "perspiciatis-veritatis-rerum-voluptatem-reprehenderit-earum-rerum-quod",
            "published_at": "2018-04-12T23:31:59.000000Z",
        },
        {
            "id": 2,
            "title": "Sed aut dolor consequuntur distinctio.",
            "slug": "sed-aut-dolor-consequuntur-distinctio",
            "published_at": "2018-02-11T15:01:10.000000Z",
        },
    ],
}

However, when you load the author for the post models, the UserResource will automatically be added to your post model.

public function index()
{
    return
        PostResource::collection(
            Post::query()
                ->with('author')
                ->get()
        )
    ;
}

{
    "data": [
        {
            "id": 1,
            "title": "Perspiciatis veritatis rerum voluptatem reprehenderit earum rerum quod.",
            "slug": "perspiciatis-veritatis-rerum-voluptatem-reprehenderit-earum-rerum-quod",
            "published_at": "2018-04-12T23:31:59.000000Z",
            "author": {
                "id": 1,
                "name": "Afton Botsford",
            },
        },
        {
            "id": 2,
            "title": "Sed aut dolor consequuntur distinctio.",
            "slug": "sed-aut-dolor-consequuntur-distinctio",
            "published_at": "2018-02-11T15:01:10.000000Z",
            "author": {
                "id": 1,
                "name": "Afton Botsford",
            },
        },
    ],
}

Including a nested to-many relationship

This package does include a breaking change compared to the way laravel serializes nested collections. Laravel doesn't wrap nested resource collections. However, this package does! If nested resource collections weren't wrapped, we could not add meta data (with abilities for example) to the nested collection. Therefore, please make sure to understand the difference:

public function index()
{
    return
        UserResource::make(
            User::query()
                ->with('posts')
                ->first()
        )
    ;
}

The query above results in the following responses:

Our package:

{
    "data": {
        "id": 1,
        "name": "Afton Botsford",
        "posts": {
            data: [
                {
                    "id": 1,
                    "title": "Perspiciatis veritatis rerum voluptatem reprehenderit earum rerum quod.",
                    "slug": "perspiciatis-veritatis-rerum-voluptatem-reprehenderit-earum-rerum-quod",
                    "published_at": "2018-04-12T23:31:59.000000Z",
                },
                {
                    "id": 2,
                    "title": "Sed aut dolor consequuntur distinctio.",
                    "slug": "sed-aut-dolor-consequuntur-distinctio",
                    "published_at": "2018-02-11T15:01:10.000000Z",
                },
            ],
        },
    },
}

Laravel:

{
    "data": {
        "id": 1,
        "name": "Afton Botsford",
        "posts": [
            {
                "id": 1,
                "title": "Perspiciatis veritatis rerum voluptatem reprehenderit earum rerum quod.",
                "slug": "perspiciatis-veritatis-rerum-voluptatem-reprehenderit-earum-rerum-quod",
                "published_at": "2018-04-12T23:31:59.000000Z",
            },
            {
                "id": 2,
                "title": "Sed aut dolor consequuntur distinctio.",
                "slug": "sed-aut-dolor-consequuntur-distinctio",
                "published_at": "2018-02-11T15:01:10.000000Z",
            },
        ],
    },
}