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. Hooks can append additional switch commands to the same SSH session (e.g., MTU, ACLs, storm control) or execute other operations (logging, external automation, validation).

The hook system supports both generic hooks (catch all operations) and specific hooks (catch only specific actions). Both execute if registered - generic hook fires first, then the specific hook.

Interface Hooks

Hook	Description
`switchFacade.interface`	Generic hook - catches ALL interface operations. Use `$action` to determine operation.
`switchFacade.interface.enableInterface`	Triggered when an interface is enabled. Can append commands.
`switchFacade.interface.disableInterface`	Triggered when an interface is disabled. Can append commands.
`switchFacade.interface.setInterfaceDescription`	Triggered when an interface description is set. Can append commands.
`switchFacade.interface.updateInterface`	Triggered when interface configuration is updated (VLANs, port mode, ...). Can append commands.

VLAN Hooks

Hook	Description
`switchFacade.vlan`	Generic hook - catches ALL VLAN operations. Use `$action` to determine operation.
`switchFacade.vlan.createVlan`	Triggered when a VLAN is created (after L3 IPs are configured). Can append commands.
`switchFacade.vlan.updateVlan`	Triggered when a VLAN is updated (name, L3 IPs). Can append commands.
`switchFacade.vlan.deleteVlan`	Triggered when a VLAN is deleted. Can append commands.
`switchFacade.vlan.setDhcpRelayIp`	Triggered when DHCP relay IP is configured on a VLAN. Can append commands.

PoE Interface Hooks

Hook	Description
`switchFacade.poeInterface`	Generic hook - catches ALL PoE operations. Use `$action` to determine operation.
`switchFacade.poeInterface.enableInterface`	Triggered when PoE is enabled on an interface. Can append commands.
`switchFacade.poeInterface.disableInterface`	Triggered when PoE is disabled on an interface. Can append commands.

Commit Hooks

Hook	Description
`switchFacade.beforeCommit`	Triggered before commit. Last chance to append commands to the same commit.
`switchFacade.afterCommit`	Triggered after successful commit. Do not append switch commands here.
`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. Can append commands to test.
`switchFacade.afterTestCommit`	Triggered after test commit. Can be used to perform additional validation or logging of test results. Do not append switch commands here.

Output Modifier Hooks

Hook	Description
`switchFacade.getVlans.outputModifier`	Modifies VLAN data before returning. Return the modified array.
`switchFacade.getInterfaces.outputModifier`	Modifies interface data before returning. Return the modified array.
`switchFacade.getPoeInterfaces.outputModifier`	Modifies PoE interface data before returning. Return the modified array.

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.
`server.install.pxe.windows.unattendTemplateOverride`	Triggered when starting a Windows PXE installation. Can be used to override the default unattend template.

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.

Other Hooks

Other hooks that don't fit into any of the above categories.

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.
`script.hardwareCollectorScript.override`	Allows overriding the hardware inventory collection shell script. The default script is passed as the first 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 are 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.