README

Helpers and routes to help build a RESTful & HAL-compliant API in Mezzio.

Installation

Install this library using composer:

$ composer require sobored/mezzio-rest-helpers

RestDispatchTrait

Use this trait for an easy way to create RESTful responses:

<?php

declare(strict_types=1);

namespace App\Handler;

use Mezzio\Hal\HalResponseFactory;
use Mezzio\Hal\ResourceGenerator;
use App\Entity\UserEntity;
use App\TableGateway\UserTableGateway;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use SoBoRed\Mezzio\Rest\Exception\NoResourceFoundException;
use SoBoRed\Mezzio\Rest\RestDispatchTrait;

class GetUserHandler implements RequestHandlerInterface
{
    /**
     * @var UserTableGateway
     */
    private $userTable;

    /**
     * Use REST Helper RestDispatchTrait to gain
     * $this->resourceGenerator, $this->responseFactory,
     * and $this->createResponse()
     */
    use RestDispatchTrait;

    public function __construct(
        UserTableGateway $userTable,
        ResourceGenerator $resourceGenerator,
        HalResponseFactory $responseFactory
    )
    {
        $this->userTable = $userTable;
        $this->resourceGenerator = $resourceGenerator;
        $this->responseFactory = $responseFactory;
    }

    public function handle(ServerRequestInterface $request) : ResponseInterface
    {
        $id = $request->getAttribute('id', false);
        $user = $this->userTable->get((int)$id)->current();

        if (! $user instanceof UserEntity) {
            // Throw a REST Helper Exception for HAL-compliant problem details in response
            throw NoResourceFoundException::create("User with id `{$id}` not found");
        }

        // Return a HAL-compliant response that contains the record requested
        return $this->createResponse($request, $user);
    }
}

Exceptions

SoBoRed/mezzio-rest-helpers comes with helpful exceptions that use mezzio/mezzio-problem-details to produce human-readable responses for API errors. An example response for NoResourceFoundException, used above, would be:

{
  "status": 404,
  "detail": "User with id `22` not found",
  "type": "/api/doc/resource-not-found",
  "title": "Resource not found"
}

Available exceptions

• Status 400: InvalidParameterException, OutOfBoundsException
• Status 405: MethodNotAllowedException
• Status 404: NoResourceFoundException
• Status 500: RuntimeException

Docs

For the problem details to be HAL-compliant, they should point to some form of documentation that helps the user understand the problem they are encountering. For this reason, mezzio-rest-helpers provides documentation and routes for it, which each exception's type points to.

Available doc routes

• /api/doc/invalid-parameter
• /api/doc/method-not-allowed-error
• /api/doc/resource-not-found
• /api/doc/parameter-out-of-range
• /api/doc/runtime-error