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.
Triedy parametrov
| Trieda | Číta z | Poznámky |
|---|---|---|
GetInputParam | query string | podporuje typy a setMulti() |
PostInputParam | telo formulára, $_POST | podporuje typy a setMulti() |
PutInputParam | form-encoded telo ľubovoľnej metódy | bez prevodu typu, typ sa ale kontroluje: INTEGER odmietne aj "12", použite STRING alebo žiadny typ |
PathInputParam | pomenovaný {placeholder} v URL endpointu | vždy povinný, pozrite nižšie |
HeaderInputParam | HTTP hlavička, bez ohľadu na veľkosť písmen | pozrite nižšie |
BodyInputParam | jedno pole tela JSON, formulára alebo multipart | pozrite nižšie |
CookieInputParam | cookie | bez prevodu typu, typ sa ale kontroluje: INTEGER odmietne aj "12", použite STRING alebo žiadny typ |
FileInputParam | nahraný súbor, $_FILES | setMulti() pre viac súborov |
RawInputParam | celé telo požiadavky ako reťazec | setMulti() vyhodí výnimku |
JsonInputParam | celé telo požiadavky dekódované ako JSON | potrebuje 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:
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
| Typ | Prevod |
|---|---|
INTEGER, DOUBLE, FLOAT | číselné reťazce sa prevedú |
BOOLEAN | 1, true (bez ohľadu na veľkosť písmen) sú true, všetko ostatné false |
STRING | ostane, ako je |
ARRAY | musí 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:
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
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:
{"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.