Preskočiť na obsah

Handlery ​

Handler je kód jedného endpointu. Implementuje Tomaj\NetteApi\Handlers\ApiHandlerInterface; v praxi dedíte z jednej z dvoch rovnocenných základných tried, podľa toho, ako chcete deklarovať vstup:

  • BaseHandler: vstup vymenujete v params() a čítate ho ako pole v handle(array $params).
  • TypedHandler: vstup opíšete ako readonly DTO s #[Query], #[Path], #[Header], #[Body] a #[File] a čítate ho ako objekt v handleDto(SomeInput $input). Pozrite Typovaný vstup (DTO).

Oba skončia ako rovnaké objekty InputParam, takže validačný pipeline, chybové odpovede, OpenAPI aj webová konzola sú spoločné. Líši sa len konverzia: typované DTO konvertuje striktne (?page=1a je 400), zatiaľ čo params() si ponecháva voľnejšiu konverziu, pozrite Vstupné parametre. Jedno API môže kombinovať oba.

Otvoriť diagram v plnej veľkosti

Metódy ​

MetódaPredvolená hodnota v BaseHandlerPoužíva
handle(array $params): ResponseInterfaceabstraktná, píšete ju vy; TypedHandler ju implementuje a volá handleDto()ApiPresenter
params(): array[]; TypedHandler ho zostaví z DTOvalidácia, OpenAPI, konzola
outputs(): array[]kontrola výstupu, OpenAPI
summary(): string''OpenAPI, konzola
description(): string''OpenAPI, konzola
tags(): array[]OpenAPI
deprecated(): boolfalseOpenAPI

handle() dostane hodnoty parametrov podľa ich názvov; handleDto() dostane DTO. Vracia odpoveď, napríklad JsonApiResponse, pozrite si Výstupy a odpovede.

php
<?php

declare(strict_types=1);

namespace App\Api;

use App\Model\UserRepository;
use Tomaj\NetteApi\Handlers\BaseHandler;
use Tomaj\NetteApi\Params\GetInputParam;
use Tomaj\NetteApi\Response\JsonApiResponse;
use Tomaj\NetteApi\Response\ResponseInterface;
use Tomaj\NetteApi\Validation\InputType;

final class UserDetailHandler extends BaseHandler
{
    public function __construct(private UserRepository $users)
    {
        parent::__construct();
    }

    public function summary(): string
    {
        return 'Get one user';
    }

    public function params(): array
    {
        return [
            (new GetInputParam('id', InputType::INTEGER))->setRequired(),
        ];
    }

    public function handle(array $params): ResponseInterface
    {
        $user = $this->users->find($params['id']);
        if ($user === null) {
            return new JsonApiResponse(404, ['status' => 'error', 'message' => 'User not found']);
        }
        return new JsonApiResponse(200, ['id' => $user->id, 'name' => $user->name]);
    }
}
php
<?php

declare(strict_types=1);

namespace App\Api;

use App\Model\UserRepository;
use Tomaj\NetteApi\Handlers\TypedHandler;
use Tomaj\NetteApi\Input\Query;
use Tomaj\NetteApi\Response\JsonApiResponse;
use Tomaj\NetteApi\Response\ResponseInterface;

final readonly class UserDetailInput
{
    public function __construct(
        #[Query]
        public int $id,
    ) {
    }
}

final class UserDetailHandler extends TypedHandler
{
    public function __construct(private UserRepository $users)
    {
        parent::__construct();
    }

    public function summary(): string
    {
        return 'Get one user';
    }

    public function handleDto(UserDetailInput $input): ResponseInterface
    {
        $user = $this->users->find($input->id);
        if ($user === null) {
            return new JsonApiResponse(404, ['status' => 'error', 'message' => 'User not found']);
        }
        return new JsonApiResponse(200, ['id' => $user->id, 'name' => $user->name]);
    }
}

BaseHandler má konštruktor s voliteľným Fractal ScopeFactoryInterface. Keď má váš handler vlastný konštruktor, zavolajte parent::__construct().

Registrácia handlera ​

ApiDecider::addApi() berie endpoint, handler, autorizáciu a voliteľné obmedzenie požiadaviek:

yaml
services:
	- App\Api\UserDetailHandler
	apiDecider:
		factory: Tomaj\NetteApi\ApiDecider
		setup:
			- addApi(Tomaj\NetteApi\EndpointIdentifier('GET', 1, 'users', 'detail'), App\Api\UserDetailHandler, Tomaj\NetteApi\Authorization\NoAuthorization())

Handler môže byť objekt alebo názov triedy. Názov triedy sa hľadá v DI kontajneri až pri volaní endpointu, takže handler s ťažkými závislosťami nič nestojí pri iných požiadavkách. Zároveň to rieši cyklické závislosti, napríklad pre OpenApiHandler, ktorý potrebuje samotný ApiDecider.

Vlastný endpoint ​

ApiDecider zavolá setEndpointIdentifier() pred handle(), takže $this->getEndpoint() vráti nájdený endpoint. Príklad autorizácie vracia getEndpoint()->getUrl(), čo je pre tú routu v1/bearer/.

createLink() vytvorí absolútny odkaz na ten istý endpoint, keď predtým zavoláte setupLinkGenerator() s Nette LinkGenerator (riadok setup v neon, pozrite si Odkazy); bez neho vyhodí Nette\InvalidStateException. Odkazy na iné endpointy opisujú Odkazy a verzie.

Handlery, ktoré sú súčasťou knižnice ​

TriedaČo robí
DefaultHandlerZastupuje neznámy endpoint; presenter odpovie 404 Unknown api endpoint cez metódu handleNotFound() error handlera. Od verzie 4.0.0 je final.
AlwaysOkHandlerVráti 200 {"status":"ok"}, hodí sa na health check.
EchoHandlerVráti povinný status (ok alebo error) a všetky svoje parametre, na testovanie.
CorsPreflightHandlerOdpovedá na OPTIONS požiadavky, pozrite si CORS.
OpenApiHandlerOpenAPI dokument, pozrite si OpenAPI.
ApiListingHandlerJSON zoznam endpointov vo vlastnej verzii.

Časté otázky ​

Musia byť handlery služby? ​

Nie, addApi() prijme aj objekt vytvorený v neon setupe. Ako služby ich registrujte, keď potrebujú autowirované závislosti. Robí to príklad parametrov.

Ako vrátim iný stavový kód? ​

Odovzdajte ho ako prvý argument odpovede, napríklad new JsonApiResponse(404, [...]). Pozrite si Výstupy a odpovede.

Mám v handle() zachytávať výnimky? ​

Len keď chcete konkrétnu odpoveď. Nezachytené výnimky idú do error handlera a stane sa z nich 500. Pozrite si Spracovanie chýb.

Ako označím endpoint ako zastaraný? ​

Vráťte true z deprecated(). OpenAPI označí operáciu ako deprecated; endpoint funguje ďalej. Pozrite si OpenAPI.

Môže jeden handler obsluhovať dva endpointy? ​

Áno, zaregistrujte ho dvakrát s rôznymi EndpointIdentifier. getEndpoint() povie, ktorý bol zavolaný. Pozrite si Odkazy a verzie.

Vydané pod licenciou MIT.