<?php
namespace Lia;
/**
* A class to organize all hook names across the main package.
*/
class Hooks {
/**
* Registered hooks should return an array of patterns like `array<string rel_file_name, string url>`.
*
* @example function receive_hook(Lia\Package\Server $package_routes_are_loaded_from, array $array_of_patterns): array { return $array_of_patterns;}
*/
const PACKAGE_ROUTE_PATTERNS_LOADED = 'lia:package.route_patterns_loaded';
/**
* Called when a response is about to be loaded, before the request or response object is initialized. No arguments are passed to these hooks, and return values are discarded.
*
* Previously, this hook was followed by 'PreAllPackagesReady' and 'AllPackagesReady', but both of those hooks have been removed.
*
* method signature: function(): void;
*
* This can be used to do initial setup that should occur on all requests, typically to finish setting up packages. After this hook, all packages should be fully ready.
*
*/
const SERVER_START = 'lia:server.server_start';
/**
* Called after all packages are ready, before routes are selected or filtered.
*
* method signature: function(\Lia\Obj\Request $request, \Lia\Obj\Response $response): void;
*
* This is a good time to add extra routes in special circumstances.
*
* For example, to add an extra layer of protection to admin routes, you should only add them if the logged-in-user is already verified as an admin. But user-role checks require database access, so this adds extra computation. Therefore, you might use REQUEST_STARTED hook to check if the request is to `/admin/...` and ONLY then check the user role and add the admin routes.
*
*
*/
const REQUEST_STARTED = 'lia:server.request_started';
/**
* Called after a view's content has been loaded. Provides an opportunity to modify this content.
* This only supports having one registered handler. More than one registered will throw exception
*
* @param $view is a file path or a callable. Callable may be an anonymous function or an array (`[$obj, 'method']`) or string 'some_function'.
* @return string content The original content will be replaced with whatever the hook handler returns
* function handle_view_loaded(?string $namespace, string $view_name, array $view, string $content): string
*
*/
const VIEW_LOADED = 'lia:server.view_loaded';
/**
* Called after the list of matching routes is loaded. The list of routes can NOT be modified here. Use `FILTER_ROUTE` for that.
*
* @param $routeList array<int index, \Lia\Obj\Route route> array of matching routes
* @example function handle_route_found(array $routeList): void {}
*
*/
const ROUTES_FOUND = 'lia:server.routes_found';
/**
* Called after the list of possible routes is reduced to one route, before the route is processed (before page content is rendered).
*
* You cannot modify the route, but you can throw an exception or `exit`, or check user access.
*
* @param $route the requested url, params, and target on the server
* function handle_routes_filtered(\Lia\Obj\Route $route): void {}
*
*/
const ROUTES_FILTERED = 'lia:server.routes_filtered';
/**
* Called after a route is processed & page content is rendered, before the theme is applied. You can modify the response headers and content.
*
* @param $route the requested url, params, and target on the server
* @param $response HTTP Headers and response content (theme has not been applied yet).
* function handle_route_resolved(\Lia\Obj\Route $route, \Lia\Obj\Response $response): void {}
*
*/
const ROUTE_RESOLVED = 'lia:server.routes_resolved';
/**
* Called after response content has been loaded, and then passed into the theme. This hook is passed a string which is the theme view (*with response content already passed into it*).
*
* This hook is a notification-only, and likely has little use.
*
* @param $theme_content string the theme view with response content already passed into it
* @example
function handle_theme_loaded(string $page_output): void
{
// i don't know why you would want to do this
custom_log_function("Full response is ".strlen($page_output). " characters.");
}
*
*/
const THEME_LOADED = 'lia:server.theme_loaded';
/**
* Called after response has been sent to the browser.
*
* A 'RequestFinished' hook was previously called after this one, but it has been removed.
*
* This hook is a notification-only, and you may use it to close database connections, file handles, or perform other cleanup.
*
* **Note:** The connection to the browser is likely still open, and the server likely will not send the buffer until after this is finished, so long cleanup operations are not recommended.
*
* @param $response \Lia\Obj\Response The response object, which contains the content that was sent to the browser, and the headers.
* @example
function handle_response_sent(\Lia\Obj\Response $response): void
{
fclose($this->file_handle);
}
*
*/
const RESPONSE_SENT = 'lia:server.response_sent';
/**
* Called once for each matching route. If **any** FILTER_ROUTE hook returns boolean `false`, then the passed route will be removed from the routes list. A null or falsey return value will do nothing. Only strict `false` has any effect. This is called regardless the size of the route list.
*
* @param $route \Lia\Obj\Route the route being checked for filtering
* @param $routeList array<int index, \Lia\Obj\Route route> array of matching routes
* @return false to remove a route from the list.
* @example
function handle_filter_route(\Lia\Obj\Route $route, array $routeList): bool
{
if (is_bad_route($route)) return false;
else return true;
}
*
*/
const FILTER_ROUTE = 'lia:server.filter_route';
/**
* Called after a response is fully processed, just before it is sent.
*
* @param $response \Lia\Obj\Response
* @return void
* @example
* function onResponseReady(\Lia\Obj\Response $response){
* $response->content = modify_response_content_i_guess($response);
* }
*
*/
const RESPONSE_READY = 'lia:server.response_ready';
}