Preskočiť na obsah

Vstupné parametre ​

params() vracia vstupy endpointu. ApiPresenter ich všetky načíta a zvaliduje pred spustením handle(), ktorý dostane hodnoty podľa názvu.

Vstup sa dá deklarovať dvoma rovnocennými spôsobmi: cez params(), ako popisuje táto stránka, alebo ako properties typovaného DTO, ktoré číta TypedHandler::handleDto(). Oba vytvoria tieto objekty InputParam a zdieľajú validáciu, OpenAPI aj konzolu. Pri výbere pomôže Typovaný vstup (DTO) a params() a DTO vedľa seba ukazuje tie isté endpointy v oboch štýloch.

Otvoriť diagram v plnej veľkosti

Triedy parametrov ​

TriedaČíta zPoznámky
GetInputParamquery stringpodporuje typy a setMulti()
PostInputParamtelo formulára, $_POSTpodporuje typy a setMulti()
PutInputParamform-encoded telo ľubovoľnej metódybez prevodu typu, typ sa ale kontroluje: INTEGER odmietne aj "12", použite STRING alebo žiadny typ
PathInputParampomenovaný {placeholder} v URL endpointuvždy povinný, pozrite nižšie
HeaderInputParamHTTP hlavička, bez ohľadu na veľkosť písmenpozrite nižšie
BodyInputParamjedno pole tela JSON, formulára alebo multipartpozrite nižšie
CookieInputParamcookiebez prevodu typu, typ sa ale kontroluje: INTEGER odmietne aj "12", použite STRING alebo žiadny typ
FileInputParamnahraný súbor, $_FILESsetMulti() pre viac súborov
RawInputParamcelé telo požiadavky ako reťazecsetMulti() vyhodí výnimku
JsonInputParamcelé telo požiadavky dekódované ako JSONpotrebuje JSON schému; setMulti() vyhodí výnimku

Druhý argument konštruktora prvých dvoch je typ, prípad enumu Tomaj\NetteApi\Validation\InputType alebo jeho reťazcová konštanta:

php
new GetInputParam('limit', InputType::Integer);
new GetInputParam('limit', InputType::INTEGER); // reťazec 'integer', funguje rovnako

$param->getParamType() vráti, odkiaľ sa parameter číta, ako enum Params\ParamType (getType() stále vracia reťazec).

Nastavenia ​

Všetky parametre majú spoločné fluent API:

MetódaÚčinok
setRequired()null alebo '' vráti Field is required.
setDefault($value)použije sa, keď vstup chýba
setAvailableValues([...])prejdú len tieto hodnoty, inak Field contains not available value(s). Pri asociatívnom poli sú hodnotami kľúče, hodnoty poľa sú popisky pre konzolu.
setMulti()očakáva pole, ?id[]=1&id[]=2; typy a povolené hodnoty platia pre každú položku
setDescription()zobrazí sa v OpenAPI a v konzole
addExample($name, $value)zobrazí sa v OpenAPI a predvyplní v konzole

Typy ​

TypPrevod
INTEGER, DOUBLE, FLOATčíselné reťazce sa prevedú
BOOLEAN1, true (bez ohľadu na veľkosť písmen) sú true, všetko ostatné false
STRINGostane, ako je
ARRAYmusí byť pole

Hodnota, ktorá nie je číslo, sa zmení na null

V 3.x ?limit=abc s typom INTEGER nie je chyba: hodnota sa pred validáciou prevedie na null, takže voliteľný parameter prejde a povinný vráti Field is required. V handle() vždy počítajte s null. Testuje to príklad parametrov.

Parametre Path, Header a Body ​

PathInputParam číta hodnotu z URL endpointu. Placeholder deklarujte v akcii endpointu ako {name}, napríklad users/{id}/detail, ako popisuje Typovaný vstup. Parameter je vždy povinný a jeho placeholder v OpenAPI má rovnaký názov. HeaderInputParam číta hlavičku požiadavky bez ohľadu na veľkosť písmen. BodyInputParam číta jedno pole objektu JSON, URL-enkódovaného formulára alebo multipart tela a setContentTypes() nastaví akceptované media typy, ktoré dokumentuje OpenAPI a používa konzola (predvolene JSON, formulár a multipart). Telo sa číta rovnako ako v typovanom handleri: pokazené JSON alebo iný charset je chyba parametra s 400, telo s iným media typom je 415 a explicitné JSON null ostane null namiesto predvolenej hodnoty. V typovanom DTO sa z properties #[Path], #[Header] a #[Body] stanú objekty MappedInputParam s typom TYPE_PATH, TYPE_HEADER alebo TYPE_BODY; params() deklaruje tieto triedy priamo:

php
public function params(): array
{
    return [
        new PathInputParam('id', InputType::INTEGER), // vždy povinný
        new HeaderInputParam('X-Request-Id', InputType::STRING),
        (new BodyInputParam('email', InputType::STRING))
            ->setRequired()
            ->setContentTypes(['application/json', 'application/x-www-form-urlencoded']),
    ];
}

OpenAPI ich zapíše ako in: path, in: header a ako polia requestBody.

JSON telo ​

JsonInputParam berie JSON schému ako reťazec a voči nej validuje dekódované telo:

php
<?php

declare(strict_types=1);

namespace App\Api;

use App\UserRepository;
use Tomaj\NetteApi\Handlers\BaseHandler;
use Tomaj\NetteApi\Output\JsonOutput;
use Tomaj\NetteApi\Params\JsonInputParam;
use Tomaj\NetteApi\Response\JsonApiResponse;
use Tomaj\NetteApi\Response\ResponseInterface;

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

    public function summary(): string
    {
        return 'Create a user';
    }

    public function tags(): array
    {
        return ['users'];
    }

    public function params(): array
    {
        return [
            // the whole request body, validated against a JSON schema
            (new JsonInputParam('user', (string) file_get_contents(__DIR__ . '/schema/user-create.json')))
                ->setRequired()
                ->addExample('Alice', ['name' => 'Alice', 'email' => 'alice@example.com']),
        ];
    }

    public function handle(array $params): ResponseInterface
    {
        $user = $this->users->add($params['user']['name'], $params['user']['email']);
        return new JsonApiResponse(201, ['user' => $user]);
    }

    public function outputs(): array
    {
        return [
            new JsonOutput(201, (string) file_get_contents(__DIR__ . '/schema/user.json'), 'The new user'),
        ];
    }
}

Pokazený JSON vráti 400 s hláškou parsera, chýbajúce povinné telo vráti missing data.

Odpoveď 400 ​

So zapnutými detailmi chýb (pozrite si Spracovanie chýb) sú chyby vypísané pre každý parameter:

json
{"status":"error","message":"wrong input","detail":{"status":["Field contains not available value(s)"]}}

S vypnutými detailmi má odpoveď len status a message.

Časté otázky ​

Ako načítam JSON telo bez schémy? ​

Použite RawInputParam a dekódujte ho sami, alebo do JsonInputParam odovzdajte voľnú schému, napríklad {"type":"object"}.

Prečo je môj celočíselný parameter null namiesto 400? ​

Nečíselné hodnoty sa v 3.x menia na null, pozrite upozornenie vyššie. Označte parameter ako povinný alebo kontrolujte null.

Môže parameter prijať viac hodnôt? ​

Áno, setMulti() a potom pošlite name[]=a&name[]=b. Pozrite si príklad parametrov.

Kde sa zobrazia príklady, ktoré pridám? ​

V OpenAPI dokumente a ako predvyplnené hodnoty vo webovej konzole.

Môže autorizácia čítať parametre? ​

Načítané hodnoty nie. authorized() nemá argumenty; hodnotu si prečítajte z HTTP požiadavky sami, ako to robí QueryApiKeyAuthentication. Parametre sa načítajú pred autorizáciou, ale dostane ich len error handler, viac v Spracovaní v ApiPresenteri.

Vydané pod licenciou MIT.