System Hooks
The system provides hooks that allow developers to execute their own code at specific points in the application lifecycle.
The hooks must be defined in the directory /var/www/html/app/Custom/Hooks/ and the directory contains two examples:
- routeHooksExample.php.example
- switchFacadeHooks.php.example
To use a hook, a hook implementation must be created.
Route Hooks
Route hooks are triggered during API request processing and allow modification of request data or response data. These hooks run at specific points in the request lifecycle, so developers can intercept and modify both incoming requests and outgoing responses.
How to find the route name
To find the route name, log in via SSH to your Tenantos server and execute this command:
app route:list
- Example route:
servers.ipassignments.destroy - Example hook:
route.post.afterResponseTransform.servers.ipassignments.destroy
Pre-Request Hooks
Pre-request hooks are executed before the primary controller logic runs. They allow you to examine and modify incoming request data before it's processed by the application.
| Hook | Description |
|---|---|
route.pre.beforePermissionChecks |
Executed before permission checks are performed. Can modify the incoming request data. |
route.pre.beforePermissionChecks.{routeName} |
Route-specific version that only runs for the specified route. Same execution point as the global hook, but limited to a specific route. |
route.pre.afterPermissionChecks |
Executed after permission checks but before the controller method. |
route.pre.afterPermissionChecks.{routeName} |
Route-specific version that only runs for the specified route. Same timing as the global hook, but for a specific route only. |
beforePermissionChecks
Executed before permission checks are performed. Can modify the incoming request data. This hook runs at the very beginning of request processing, before any validation has occurred. Request could be denied at this stage if parameters are sent that the user has no permission to access.
afterPermissionChecks
Executed after permission checks but before the controller method. At this point, the system has validated that the user has permission to access the requested resource, but the controller logic hasn't executed yet. This hook can add additional parameters to which the user may not have access to according to their permissions.
Post-Response Hooks
Post-response hooks are executed after the controller has processed the request. They allow you to examine and modify the response before it's sent to the client.
| Hook | Description |
|---|---|
route.post.beforeResponseTransform |
Executed after controller generates a response but before transformers are applied. |
route.post.beforeResponseTransform.{routeName} |
Route-specific version that only runs for the specified route. |
route.post.afterResponseTransform |
Executed after all transformations. Final chance to modify response before sending to the client. |
route.post.afterResponseTransform.{routeName} |
Route-specific version that only runs for the specified route. |
beforeResponseTransform
Executed after controller generates a response but before transformers are applied. "Response transform" refers to the process of converting internal data structures to the format expected by the client (e.g., applying API resource transformers). This hook allows you to modify the raw response data before it's transformed. Parameters to which the user has no access according to their permissions will be filtered at this stage.
afterResponseTransform
Executed after all transformations. Final chance to modify response before sending to the client. The response at this point is fully formatted according to the API's expected output format. This hook can be used to add your own output since permission filtering is already done at this stage.
Terminate Hook
| Hook | Description |
|---|---|
route.terminate.{routeName} |
Executed after the response has been sent to the client. Useful for logging or cleanup tasks. |
terminate
Executed after the response has been sent to the client. This hook is only available in the route-specific form route.terminate.{routeName}. It's useful for logging or cleanup tasks. No long-running tasks should be executed in this hook because it will keep the PHP process running, even though the client has already received the response.
Switch Facade Hooks
These hooks allow customization of switch operations and data retrieval.
| Hook | Description |
|---|---|
switchFacade.getVlans.outputModifier |
Modifies the output of VLAN data retrieved from switches. Return the modified array to change the output shown to the user. |
switchFacade.getInterfaces.outputModifier |
Modifies the output of interface data retrieved from switches. Return the modified array to change the interface information displayed. |
switchFacade.getPoeInterfaces.outputModifier |
Modifies the output of PoE interface data retrieved from switches. Return the modified array to alter the PoE information. |
switchFacade.beforeCommit |
Triggered before changes are committed to a switch. Can be used to add additional commands. |
switchFacade.afterCommit |
Triggered after changes have been successfully committed to a switch. Useful for logging or executing additional operations. |
switchFacade.beforeTestCommit |
Triggered before test commit operations on switches. "Test commit" runs the configuration commands in a simulated environment without actually applying them to verify they would work correctly. |
switchFacade.afterTestCommit |
Triggered after test commit operations on switches. Can be used to perform additional validation or logging of test results. |
Server Operation Hooks
These hooks are triggered during server power and installation operations.
| Hook | Description |
|---|---|
server.power.beforePowerAction |
Triggered before a power action is executed on a server. Can return 'abort' to cancel the power action. Parameters include server ID and the power method being executed. |
server.power.afterPowerAction |
Triggered after a power action has been executed on a server. Useful for logging or additional operations related to server power state changes. |
server.install.beforeStartReinstallation |
Triggered before a server reinstallation process starts. Parameters include server ID and installation data. |
server.install.afterStartReinstallation |
Triggered after a server reinstallation process has started. Can be used for logging or additional configuration after installation begins. |
Frontend Hooks
Hooks that allow injecting content into the frontend interface.
| Hook | Description |
|---|---|
render.head |
Allows injection of content into the HTML <head> section. |
render.body |
Allows injection of content into the HTML <body> section. |
Note: Tenantos is a single page application. Keep that in mind when injecting custom content like Javascript.
Service Hooks
Hooks for services like DHCP configuration.
| Hook | Description |
|---|---|
service.dhcp.hostConfiguration |
Allows modification of DHCP host configuration before it's written. The hook receives the DHCP template string and should return the modified template string. The agent ID is also provided as a parameter. |
How to Create a New Hook Implementation
Please refer to the example files:
/var/www/html/app/Custom/Hooks/routeHooksExample.php.example/var/www/html/app/Custom/Hooks/switchFacadeHooks.php.example
Working with Hooks
Hook Function Parameters
The example files contain all the necessary information about what parameters are passed to each hook function. Be sure to check these files for the specific parameters for the hook you're implementing.
Response Manipulation
The example files contain all information. For completeness, here is a summary:
- If you want to inspect the response body using the route hooks, use the
getResponseContent()helper function to easily extract the body of the response. - If you want to manipulate the response, use the
response()helper function.