API resource eager loading, simplified

option-1.php

<?php

class OrganisationUserGroupsController
{
    public function index(ListOrganisationUserGroupsRequest $request, Organisation $organisation)
    {
        $userGroups = $organisation->userGroups()
            ->applyFilters($request->filters())
            ->paginate();
        
        return UserGroupCollection::make($userGroups)
            ->includeUsersIf($request->shouldInclude('users'));
    }
}

class UserGroupCollection extends JsonResource
{
    public function toArray($request)
    {
        return parent::toArray($request);
    }
    
    public function includeUsersIf(bool $shouldInclude)
    {
        if (! $shouldInclude) {
            return $this;
        }
        
        return $this->additional([
            'included' => [
                'users' => $this->userGroups()
                    ->load('users')
                    ->mapWithKeys(function (UserGroup $userGroup) {
                        return [ $userGroup->getKey() => UserCollection::make($userGroup->users)];
                    });
            ],
        ]);
    }
    
    private function userGroups(): Collection
    {
        return Collection::wrap($this->collection->map->resource->all());
    }
}

option-2.php

<?php

class OrganisationUserGroupsController
{
    public function index(ListOrganisationUserGroupsRequest $request, Organisation $organisation)
    {
        $userGroups = $organisation->userGroups()
            ->applyFilters($request->filters())
            ->with($request->includes())
            ->paginate();
        
        return UserGroupCollection::make($userGroups)
            ->includeUsersIf($request->shouldInclude('users'));
    }
}

class UserGroupCollection extends JsonResource
{
    public function toArray($request)
    {
        return parent::toArray($request);
    }
    
    public function includeUsersIf(bool $shouldInclude)
    {
        if (! $shouldInclude) {
            return $this;
        }
        
        return $this->additional([
            'included' => [
                'users' => $this->collection
                    ->map->resource
                    ->mapWithKeys(function (UserGroup $userGroup) {
                        return [ $userGroup->getKey() => UserCollection::make($userGroup->users)];
                    });
            ],
        ]);
    }
}