Json Api Document Builder

This library resolve Query Object to JSON:API Documents.

Features

• Pagination, sorting, filtering with the following operators (eq, neq, gt, lt, gte, lte, like).
• Multiple nested paths resource inclusion (e.g. article, article.author, article.comments.user).
• Async resource inclusion (Guzzle Promises/A+).
• Caching resolved resources.
• Fully Unit tested

Request examples:

GET /api/v1/articles/{id}?include=author
GET /api/v1/articles?include=author,comments.user&page=1&per_page=15
GET /api/v1/articles?sort=id,-title // sort id in asc, title in desc 
GET /api/v1/articles?filter[id]=100,101&filter[title][like]=value

Requirements

• PHP version >=8.0

Installation

Use composer to install the package:

composer require coder-sapient/json-api-document-builder

Basic Usage

Controller action example:

final class ShowArticleAction
{
    public function __construct(private SingleDocumentBuilder $builder)
    {
    }

    public function __invoke(ShowArticleRequest $request): string
    {
        try {
            $document = $this->builder->build($request->toQuery());
        } catch (JsonApiException $e) {
            return json_encode($e->jsonApiErrors());
        }

        return json_encode($document);
    }
}

You can add the following traits to your request classes:

• SingleDocumentRequest: For documents about a single top-level resource.
• DocumentsRequest: For documents about a collection of top-level resources.

SingleDocumentRequest

final class ShowArticleRequest extends Request
{
    use SingleDocumentRequest;

    protected function resourceId(): string
    {
        // return from URL ~/articles/{resourceId}  
    }

    protected function resourceType(): string
    {
        return 'articles';
    }

    protected function acceptableIncludes(): array
    {
        return ['author', 'comments', 'comments.user'];
    }
}

DocumentsRequest

final class ListArticlesRequest extends Request
{
    use DocumentsRequest;

    protected function resourceType(): string
    {
        return 'articles';
    }
    
    protected function acceptableSorting(): array
    {
        return ['title', 'created_at'];
    }
    
    protected function acceptableIncludes(): array
    {
        return ['author', 'comments', 'comments.user'];
    }

    protected function acceptableFilters(): array
    {
        return ['author_id' => ['eq'], 'title' => ['eq', 'like']];
    }
}

Factory

The ResourceResolverFactory is a factory that return a ResourceResolver by resource type.

interface ResourceResolverFactory
{
    /**
     * @throws ResourceResolverNotFoundException
     */
    public function make(string $resourceType): ResourceResolver;
}

There is a basic implementation InMemoryResourceResolverFactory:

$factory = new InMemoryResourceResolverFactory();

$factory->add(
    'articles', // resource type
    new ArticleResourceResolver()
);
$factory->add(
    'users', 
    new AuthorResourceResolver()
);
$factory->add(
    'comments',
    new CommentResourceResolver()
);

ResourceResolver

The builder use instances of ResourceResolver to find resources by ids or query criteria.

interface ResourceResolver
{
    /**
     * @param DocumentsQuery $query
     *
     * @return ResourceObject[]
     */
    public function resolveMany(DocumentsQuery $query): array;

    /**
     * @param SingleDocumentQuery $query
     *
     * @return ResourceObject|null
     */
    public function resolveOne(SingleDocumentQuery $query): ?ResourceObject;

    /**
     * @param string ...$resourceIds
     *
     * @return ResourceObject[]|PromiseInterface
     */
    public function resolveByIds(string ...$resourceIds): array|PromiseInterface;
}

ResourceCache

The builder caches all resolved resources using instance of ResourceCache.

interface ResourceCache
{
    /**
     * @param string $key
     *
     * @return ResourceObject|null
     */
    public function getByKey(string $key): ?ResourceObject;

    /**
     * @return ResourceObject[]
     */
    public function getByKeys(string ...$keys): array;

    /**
     * @param JsonApiQuery $query
     *
     * @return ResourceObject[]
     */
    public function getByQuery(JsonApiQuery $query): array;

    /**
     * @param ResourceObject ...$resources
     *
     * @return void
     */
    public function setByKeys(ResourceObject ...$resources): void;

    /**
     * @param JsonApiQuery $query
     * @param ResourceObject ...$resources
     *
     * @return void
     */
    public function setByQuery(JsonApiQuery $query, ResourceObject ...$resources): void;

    /**
     * @param string ...$keys
     *
     * @return void
     */
    public function removeByKeys(string ...$keys): void;

    /**
     * @param string ...$resourceTypes
     *
     * @return void
     */
    public function removeByTypes(string ...$resourceTypes): void;

    /**
     * @return void
     */
    public function flush(): void;
}

There is a basic implementation InMemoryResourceCache. If you don't need caching, use NullableResourceCache.

SingleDocumentBuilder

$builder = new SingleDocumentBuilder($factory, new InMemoryResourceCache());

$singleDocument = $builder->build($request->toQuery());

DocumentsBuilder

$builder = new DocumentsBuilder($factory, new InMemoryResourceCache());

$documents = $builder->build($request->toQuery());

When resolving a collection of top-level resources, it will provide a query criteria consisting of filters, orders, pagination. You need to match criteria with your query builder (Doctrine, Eloquent, etc.).

The builder can accept Guzzle Promises when trying to include related resources and load them async.

PaginationResolver

interface PaginationResolver
{
    /**
     * @param DocumentsQuery $query
     *
     * @return PaginationResponse
     */
    public function paginate(DocumentsQuery $query): PaginationResponse;
}

If the resource resolver implements PaginationResolver, the builder will add top-level Links and Meta objects to the resulting document.

{
  "links": {
    "first": "http://localhost/api/v1/articles?page=1&per_page=15",
    "prev": "http://localhost/api/v1/articles?page=1&per_page=15",
    "next": "http://localhost/api/v1/articles?page=2&per_page=15",
    "last": "http://localhost/api/v1/articles?page=3&per_page=15",
  },
  "meta": {
    "total": 45,
    "page": 1,
    "per_page": 15,
    "last_page": 3
  }
}

License

The MIT License (MIT). Please see LICENSE for more information.