Input params
params() returns the inputs of the endpoint. ApiPresenter reads and validates all of them before handle() runs, and handle() gets the values keyed by name.
Input can be declared in two equal ways: with params(), as described on this page, or as properties of a typed DTO read by TypedHandler::handleDto(). Both produce these InputParam objects and share validation, OpenAPI and the console. Typed input (DTO) helps you choose, and params() and DTO side by side shows the same endpoints in both styles.
Param classes
| Class | Reads from | Notes |
|---|---|---|
GetInputParam | query string | supports types and setMulti() |
PostInputParam | form body, $_POST | supports types and setMulti() |
PutInputParam | form-encoded body of any method | no type conversion, but a type is still checked: INTEGER rejects even "12", so use STRING or no type |
PathInputParam | a named {placeholder} in the endpoint URL | always required, see below |
HeaderInputParam | HTTP header, case-insensitive | see below |
BodyInputParam | one field of a JSON, form or multipart body | see below |
CookieInputParam | cookie | no type conversion, but a type is still checked: INTEGER rejects even "12", so use STRING or no type |
FileInputParam | uploaded file, $_FILES | setMulti() for several files |
RawInputParam | the whole request body as a string | setMulti() throws |
JsonInputParam | the whole request body, decoded as JSON | needs a JSON schema; setMulti() throws |
The second constructor argument of the first two is the type, a case of the Tomaj\NetteApi\Validation\InputType enum or its string constant:
new GetInputParam('limit', InputType::Integer);
new GetInputParam('limit', InputType::INTEGER); // the string 'integer', works the same$param->getParamType() returns where the param is read from as a Params\ParamType enum (getType() still returns the string).
Settings
All params share a fluent API:
| Method | Effect |
|---|---|
setRequired() | null or '' answers Field is required. |
setDefault($value) | used when the input is missing |
setAvailableValues([...]) | only these values pass, else Field contains not available value(s). Keys of an associative array are the values, the array values are labels for the console. |
setMulti() | expects an array, ?id[]=1&id[]=2; types and allowed values apply to every item |
setDescription() | shown in OpenAPI and the console |
addExample($name, $value) | shown in OpenAPI and prefilled in the console |
Types
| Type | Conversion |
|---|---|
INTEGER, DOUBLE, FLOAT | numeric strings are converted |
BOOLEAN | 1, true (any case) are true, everything else is false |
STRING | kept as it is |
ARRAY | must be an array |
A value that is not a number becomes null
In 3.x ?limit=abc with INTEGER is not an error: the value is converted to null before validation, so an optional param passes and a required one answers Field is required. Always handle null in handle(). The params example tests this.
Path, header and body params
PathInputParam reads a value from the endpoint URL. Declare the placeholder in the endpoint action with {name}, for example users/{id}/detail, as described in Typed input. The param is always required and its OpenAPI placeholder has the same name. HeaderInputParam reads a request header, case-insensitively. BodyInputParam reads one field of a JSON object, a URL-encoded form or a multipart body, and setContentTypes() sets the accepted media types, which OpenAPI documents and the console uses (JSON, form and multipart by default). The body is read like a typed handler reads it: malformed JSON or another charset is a 400 error of the param, a body of another media type is a 415, and an explicit JSON null stays null instead of taking the default. In a typed DTO, #[Path], #[Header] and #[Body] properties become MappedInputParam objects with the type TYPE_PATH, TYPE_HEADER or TYPE_BODY; params() declares these classes directly:
public function params(): array
{
return [
new PathInputParam('id', InputType::INTEGER), // always required
new HeaderInputParam('X-Request-Id', InputType::STRING),
(new BodyInputParam('email', InputType::STRING))
->setRequired()
->setContentTypes(['application/json', 'application/x-www-form-urlencoded']),
];
}OpenAPI emits them as in: path, in: header and as fields of the requestBody.
JSON body
JsonInputParam takes a JSON schema as a string and validates the decoded body against it:
<?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'),
];
}
}Broken JSON answers 400 with the parser message, a missing required body answers missing data.
The 400 response
With error details on (see Error handling), the errors are listed per param:
{"status":"error","message":"wrong input","detail":{"status":["Field contains not available value(s)"]}}With details off, the response has only status and message.
FAQ
How do I read a JSON body without a schema?
Use RawInputParam and decode it yourself, or pass a permissive schema such as {"type":"object"} to JsonInputParam.
Why is my integer param null instead of 400?
Non-numeric values become null in 3.x, see the warning above. Make the param required or check for null.
Can a param take several values?
Yes, setMulti(), then send name[]=a&name[]=b. See the params example.
Where do the examples I add show up?
In the OpenAPI document and as prefilled values in the web console.
Can authorization read the params?
Not the parsed values. authorized() takes no arguments; read the value from the HTTP request yourself, as QueryApiKeyAuthentication does. Params are read before authorization but only the error handler gets them, see ApiPresenter pipeline.