Download the PHP package vitek-dev/nette-api-controller without Composer

API Controller

Simple implementation for Nette\Application\IPresenter.

This allows to completely avoid Nette\Application\UI\Presenter and focus only on stateless API actions; ApiController avoids e.g.:

• Nette Component model (components hierarchy, forms, custom controls, etc.),
• Signals (handleAction),
• Creating links, canonicalization requests,
• Redirects,
• Templates rendering (you can manually render Latte with Latte Engine but it's not integrated directly inside the Controller)

Installation

• Add dependency composer require vitekdev/nette-api-controller
• ApiController uses PSR 3 logging, if you want to use Tracy, just register this bridge in your services config: Tracy\Bridges\Psr\TracyToPsrLoggerAdapter
• That's it, you can create your first Controller

Example

Features

Action name with request method

Expected request method is defined directly in action name.

E.g. public function getFoo(): void will accept only GET requests, public function postFoo(): void will accept only POST requests.

Auto mapping of route parameters

Route parameters are automatically mapped to action parameters.

E.g. public function getFoo(int $id): void will automatically map route parameter id to action parameter $id. Parameters itself are handled via Nette\Routing (see https://doc.nette.org/en/application/routing#toc-mask-and-parameters).

Auto mapping of request body JSON to object

All objects extending VitekDev\Nette\Application\Request\RequestBody are automatically mapped from request body JSON.

Mapping is done via ::map(array $json): self method. Some exceptions thrown here (ValidationFailed | InvalidArgumentException | DomainException) are automatically translated to HTTP 400 Bad Request.

E.g. if we have following DTO class:

We can set up following controller action just as simple as:

Validation & fully automated mapping

You can also use e.g. Nette\Schema if you want fully automated validation and/or need more complex validation.

Implementation of Nette\Schema and RequestBody is already bundled in VitekDev\Nette\Application\Request\AutoMappedRequestBody.

If you need to add some additional validation, you can override method ::getCustomRules(): array in implementing class.

Action result = Controller response

The ApiController automatically sends response with data returned from action.

Automatic handling specific Exceptions

Listed exceptions are automatically translated to VitekDev\Nette\Application\Response\StatusResponse.

• DomainException => HTTP 500 Internal Server Error (with exception message)
• VitekDev\Shared\Exceptions\AuthenticationRequired => HTTP 401 Unauthorized (with exception message)
• VitekDev\Shared\Exceptions\AuthorizationInsufficient => HTTP 403 Forbidden (with exception message)
• VitekDev\Shared\Exceptions\ResourceNotFound => HTTP 404 Not Found (with exception message)

All other errors, especially RuntimeException, are translated to HTTP 500 Internal Server Error without exception message.

Recommended Router

You can use Route as simple as: api/v1/<module>/<presenter>/<action>[/<id>] that is already bundled and ready to use: VitekDev\Nette\Application\ApiRouter.

Side notes

Stateless

The ApiController is readonly so all child classes must be readonly.