Hooks
You are reading the documentation for version 2 of FoalTS. Instructions for upgrading to this version are available here. The old documentation can be found here.
#
DescriptionHooks are decorators that execute extra logic before and/or after the execution of a controller method.
They are particulary useful in these scenarios:
- authentication & access control
- request validation & sanitization
- logging
They improve code readability and make unit testing easier.
#
Built-in HooksFoal provides a number of hooks to handle the most common scenarios.
ValidateBody
,ValidateHeader
,ValidatePathParam
,ValidateCookie
andValidateQueryParam
validate the format of the incoming HTTP requests (see Validation).Log
displays information on the request (see Logging & Debugging).JWTRequired
,JWTOptional
,UseSessions
authenticate the user by filling thectx.user
property.PermissionRequired
restricts the route access to certain users.
#
UseA hook can decorate a controller method or the controller itself. If it decorates the controller then it applies to all its methods and sub-controllers.
In the below example, JWTRequired
applies to listProducts
and addProduct
.
Example:
If the user makes a POST request to /products
whereas she/he is not authenticated, then the server will respond with a 400 error and the ValidateBody
hook and addProduct
method won't be executed.
If you need to apply a hook globally, you just have to make it decorate the root controller:
AppController
.
#
Build Custom HooksIn addition to the hooks provided by FoalTS, you can also create your own.
A hook is made of a small function, synchronous or asynchronous, that is executed before the controller method.
To create one, you need to call the Hook
function.
Example:
The hook function can take two parameters: the Context
object and the service manager. The Context object is specific to the request and gives you information on it. The service manager lets you access any service through its get
method.
Example:
A hook function can return an HttpResponse
object. If so, the remaining hooks and the controller method are not executed and the object is used to render the HTTP response.
Example:
You can also have access to the controller instance through the this
keyword.
Example
#
Executing Logic After the Controller MethodA hook can also be used to execute extra logic after the controller method. To do so, you can return a hook post function inside the hook. This function will be executed after the controller method. It takes exactly one parameter: the HttpResponse
object returned by the controller.
The below example shows how to add a custom cookie to the response returned by the controller.
This example shows how to execute logic both before and after the controller method.
#
Grouping Several Hooks into OneIn case you need to group several hooks together, the MergeHooks
function can be used to do this.
#
Testing HooksHooks can be tested thanks to the utility getHookFunction
(or getHookFunctions
if the hook was made from several functions).
#
Testing Hook Post Functionsthis
#
Testing Hooks that Use #
Mocking servicesYou can mock services by using the set
method of the service manager.
Example:
#
Hook factoriesUsually, we don't create hooks directly but with hook factories. Thus it is easier to customize the hook behavior on each route.
Example: