Controllers are the front door of your application. They intercept all incoming requests and return the responses to the client.
The code of a controller should be concise. If necessary, controllers can delegate some tasks to services (usually the business logic).
A controller is simply a class of which some methods are responsible for a route. These methods must be decorated by one of theses decorators
Options. They may be asynchronous.
Controllers may have sub-controllers declared in the
AppController is the main controller of your application. It is directly bound to the request handler. Every controller must be, directly or indirectly, a sub-controller of the
On every request, the controller method is called with a
Context object. This context is unique and specific to the request.
It has four properties:
Request) giving information about the HTTP request received,
object) which can be used to share data between hooks (see Hooks),
undefined) giving information on the current user (see Authentication),
- and a
undefined) containing the session data if you use sessions.
The request body is accessible with the
Path parameters are accessible with the
Query parameters are accessible with the
Headers are accessible with the
Cookies are accessible with the
Available in Foal v1.9.0 onwards.
The path paramaters and request body are also passed as second and third arguments to the controller method.
HTTP responses are defined using
HttpResponse objects. Each controller method must return an instance of this class (or a promise of this instance).
Here are subclasses that you can use:
| HTTP method | Response class | Is abstract? |
| | 2XX Success | |
| 2XX |
HttpResponseSuccess | yes |
| 200 |
HttpResponseOK | no |
| 201 |
HttpResponseCreated | no |
| | 3XX Redirection | |
| 3XX |
HttpResponseRedirection | yes |
| 301 |
HttpResponseMovedPermanently | no |
| 302 |
HttpResponseRedirect | no |
| | 4XX Client errors | |
| 4XX |
HttpResponseClientError | yes |
| 400 |
HttpResponseBadRequest | no |
| 401 |
HttpResponseUnauthorized | no |
| 403 |
HttpResponseForbidden | no |
| 404 |
HttpResponseNotFound | no |
| 405 |
HttpResponseMethodNotAllowed | no |
| 409 |
HttpResponseConflict | no |
| | 5XX Server errors | |
| 5XX |
HttpResponseServerError | yes |
| 500 |
HttpResponseInternalServerError | no |
| 501 |
HttpResponseNotImplemented | no |
Most of these responses accept a
body at instantiation. It can be a
Buffer object, a string, an object, a number, an array, or even a Node.JS stream.
Example with a body
In case the body parameter is a stream, you must specify it using the
Example with a Node.JS stream as body
Example with no cookie directives
Example with cookie directives
maxAgecookie directive defines the number of seconds until the cookie expires.
A controller is a simple class and so can be tested as is. Note that hooks are ignored upon testing.
Due to the way packages are managed by npm, you should always use
response instanceof HttpResponseOKto avoid reference bugs.
You can also override
foo. If you don't add a
Options decorator then the parent path and HTTP method are used. If you don't add a hook, then the parent hooks are used. Otherwise they are all discarded.