README

This project is an independently maintained fork of phoneburner/api-handler, originally released under the MIT license, by the original project authors. This fork is neither affiliated with nor endorsed by PhoneBurner.

Simple set of PSR-15 request handlers to add an API to any project. Provides CRUD operation handlers, response transformation capabilities, and middleware-based request dispatching.

Requirements

• PHP >= 8.2
• wickedbyte/http-tortilla ^3.0
• psr/http-message ^2.0
• psr/http-factory ^1.0
• psr/http-server-middleware ^1.0

Installation

The preferred method of installation is to use Composer:

composer require wickedbyte/api-handler

Usage

This library provides a set of CRUD handlers (CreateHandler, ReadHandler, UpdateHandler, DeleteHandler) that implement Psr\Http\Server\RequestHandlerInterface. Each handler is composed of small, focused interfaces:

• Resolver — Resolves a domain object from the incoming request (e.g. fetch an entity by ID).
• Hydrator — Creates, updates, or deletes a domain object based on the request.
• Transformer — Transforms a domain object into the response body content.
• ResponseFactory — Builds the PSR-7 response from a TransformableResource.

Handlers can be dispatched via the included DispatchMiddleware, which uses a HandlerFactory to route requests to the appropriate handler:

<?php

declare(strict_types=1);

use WickedByte\ApiHandler\DispatchMiddleware;

// HandlerFactory decides which handler (if any) should process a request
$middleware = new DispatchMiddleware($handlerFactory);

// In your middleware pipeline, the middleware will dispatch to the
// appropriate handler if the factory can handle the request, or
// pass through to the next handler in the pipeline.
$response = $middleware->process($request, $fallbackHandler);

Examples

A typical read endpoint that resolves an entity and transforms it to JSON:

<?php

declare(strict_types=1);

use Psr\Http\Message\ServerRequestInterface;
use WickedByte\ApiHandler\ReadHandler;
use WickedByte\ApiHandler\Resolver;
use WickedByte\ApiHandler\Transformer;

// Implement Resolver to fetch your domain object from the request
$resolver = new class implements Resolver {
    public function resolve(ServerRequestInterface $request): object
    {
        $id = $request->getAttribute('id');
        return $repository->find($id);
    }
};

// Implement Transformer to convert the domain object to response content
$transformer = new class implements Transformer {
    public function transform(object $resource, ServerRequestInterface $request): mixed
    {
        return ['id' => $resource->id, 'name' => $resource->name];
    }
};

$handler = new ReadHandler($resolver, $transformer);
$handler->setResponseFactory($responseFactory);

$response = $handler->handle($request); // 200 response with transformed content

Contributing

Contributions are welcome, please see CONTRIBUTING.md for more information, including reporting bugs and creating pull requests.

Coordinated Disclosure

Keeping user information safe and secure is a top priority, and we welcome the contribution of external security researchers. If you believe you've found a security issue, please read SECURITY.md for instructions on submitting a vulnerability report.