ResourceCollection.php

TLDR

This file defines the ResourceCollection class, which is a subclass of JsonResource. It also implements the Countable and IteratorAggregate interfaces. The class is used to transform a collection of resources into a JSON array. It provides methods to append query parameters to pagination links and create paginate-aware HTTP responses.

Methods

__construct

The __construct method initializes a new ResourceCollection instance. It calls the parent constructor to set the resource and then collects the resource using the collectResource method.

preserveQuery

The preserveQuery method indicates that all current query parameters should be appended to pagination links. It sets the preserveAllQueryParameters property to true.

withQuery

The withQuery method specifies the query string parameters that should be present on pagination links. It sets the queryParameters property to the provided array of query parameters.

count

The count method returns the count of items in the resource collection. It delegates the count to the collection property using the count method.

toArray

The toArray method transforms the resource into a JSON array. It maps each item in the collection property to an array representation using the toArray method and returns the resulting array.

toResponse

The toResponse method creates an HTTP response that represents the object. If the $resource property is an instance of AbstractPaginator or AbstractCursorPaginator, it delegates the response creation to the preparePaginatedResponse method. Otherwise, it calls the parent toResponse method.

preparePaginatedResponse

The preparePaginatedResponse method creates a paginate-aware HTTP response. If preserveAllQueryParameters is true, it appends all current query parameters to the pagination links using the appends method. If queryParameters is not null, it appends the specified query parameters. Finally, it creates a new PaginatedResourceResponse instance and returns the response by calling its toResponse method.

Classes

No classes in this file.

<?php

namespace Illuminate\Http\Resources\Json;

use Countable;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\CollectsResources;
use Illuminate\Pagination\AbstractCursorPaginator;
use Illuminate\Pagination\AbstractPaginator;
use IteratorAggregate;

class ResourceCollection extends JsonResource implements Countable, IteratorAggregate
{
    use CollectsResources;

    /**
     * The resource that this resource collects.
     *
     * @var string
     */
    public $collects;

    /**
     * The mapped collection instance.
     *
     * @var \Illuminate\Support\Collection
     */
    public $collection;

    /**
     * Indicates if all existing request query parameters should be added to pagination links.
     *
     * @var bool
     */
    protected $preserveAllQueryParameters = false;

    /**
     * The query parameters that should be added to the pagination links.
     *
     * @var array|null
     */
    protected $queryParameters;

    /**
     * Create a new resource instance.
     *
     * @param  mixed  $resource
     * @return void
     */
    public function __construct($resource)
    {
        parent::__construct($resource);

        $this->resource = $this->collectResource($resource);
    }

    /**
     * Indicate that all current query parameters should be appended to pagination links.
     *
     * @return $this
     */
    public function preserveQuery()
    {
        $this->preserveAllQueryParameters = true;

        return $this;
    }

    /**
     * Specify the query string parameters that should be present on pagination links.
     *
     * @param  array  $query
     * @return $this
     */
    public function withQuery(array $query)
    {
        $this->preserveAllQueryParameters = false;

        $this->queryParameters = $query;

        return $this;
    }

    /**
     * Return the count of items in the resource collection.
     *
     * @return int
     */
    public function count(): int
    {
        return $this->collection->count();
    }

    /**
     * Transform the resource into a JSON array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array|\Illuminate\Contracts\Support\Arrayable|\JsonSerializable
     */
    public function toArray(Request $request)
    {
        return $this->collection->map->toArray($request)->all();
    }

    /**
     * Create an HTTP response that represents the object.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function toResponse($request)
    {
        if ($this->resource instanceof AbstractPaginator || $this->resource instanceof AbstractCursorPaginator) {
            return $this->preparePaginatedResponse($request);
        }

        return parent::toResponse($request);
    }

    /**
     * Create a paginate-aware HTTP response.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\JsonResponse
     */
    protected function preparePaginatedResponse($request)
    {
        if ($this->preserveAllQueryParameters) {
            $this->resource->appends($request->query());
        } elseif (! is_null($this->queryParameters)) {
            $this->resource->appends($this->queryParameters);
        }

        return (new PaginatedResourceResponse($this))->toResponse($request);
    }
}