Plugin Hooks¶

This document lists all available plugin hooks in the Traq codebase, organised by hook type.

Hook Types¶

template: Hooks¶

Template hooks allow plugins to inject content into specific template locations.

template:layouts/global/head
- Location: vendor/traq/views/default/layouts/_head.phtml
- Parameters: None
- Description: Allows plugins to inject content (e.g., CSS, meta tags, scripts) into the global <head> section that appears on all pages.
template:layouts/default/head
- Location: vendor/traq/views/default/layouts/default.phtml
- Parameters: None
- Description: Allows plugins to inject content into the <head> section of the default layout template.
template:layouts/default/main_nav
- Location: vendor/traq/views/default/layouts/_nav.phtml
- Parameters: $project (optional, may be false)
- Description: Allows plugins to add navigation items to the main navigation bar. The $project parameter contains the current project object if viewing a project page, or false otherwise.
template:layouts/admin/head
- Location: vendor/traq/views/default/layouts/admin.phtml
- Parameters: None
- Description: Allows plugins to inject content into the <head> section of the admin layout template.
template:layouts/admin/main_nav
- Location: vendor/traq/views/default/layouts/admin.phtml
- Parameters: None
- Description: Allows plugins to add navigation items to the main navigation bar in the admin control panel.
template:layouts/_meta_nav/user_nav
- Location: vendor/traq/views/default/layouts/_meta_nav.phtml
- Parameters: None
- Description: Allows plugins to add items to the user navigation menu (typically shown in the top-right corner when logged in).
template:admin/settings/_nav
- Location: vendor/traq/views/default/admin/settings/_nav.phtml
- Parameters: None
- Description: Allows plugins to add navigation items to the admin settings navigation menu.
template:users/register
- Location: vendor/traq/views/default/users/register.phtml
- Parameters: None
- Description: Allows plugins to add custom fields or content to the user registration form.
template:users/usercp/info
- Location: vendor/traq/views/default/usercp/index.phtml
- Parameters: None
- Description: Allows plugins to add content to the user control panel information section.
template:users/usercp
- Location: vendor/traq/views/default/usercp/index.phtml
- Parameters: None
- Description: Allows plugins to add content to the main user control panel page.
template:users/usercp/password
- Location: vendor/traq/views/default/usercp/password.phtml
- Parameters: None
- Description: Allows plugins to add content to the user control panel password change form.
template:usercp/_nav
- Location: vendor/traq/views/default/usercp/_nav.phtml
- Parameters: $user (User object)
- Description: Allows plugins to add navigation items to the user control panel navigation menu.
template:users/users/view
- Location: vendor/traq/views/default/profile/view.phtml
- Parameters: $profile (User profile object)
- Description: Allows plugins to add content to the user profile view page.
template:projects/index/project/nav
- Location: vendor/traq/views/default/projects/index.phtml
- Parameters: $project (Project object)
- Description: Allows plugins to add navigation items for each project displayed on the projects index page.
template:projects/index/project
- Location: vendor/traq/views/default/projects/index.phtml
- Parameters: $project (Project object)
- Description: Allows plugins to add content to each project card/display on the projects index page.
template:project_settings/_nav
- Location: vendor/traq/views/default/project_settings/_nav.phtml
- Parameters: $project (Project object)
- Description: Allows plugins to add navigation items to the project settings navigation menu.
template:projectsettings/options/_form
- Location: vendor/traq/views/default/project_settings/options/_form.phtml
- Parameters: $proj (Project object)
- Description: Allows plugins to add custom fields or content to the project settings options form.

controller: Hooks¶

Controller hooks allow plugins to intercept or modify controller actions.

controller:users.register
- Location: vendor/traq/controllers/users.php
- Parameters: &$user (User model, passed by reference)
- Description: Called during user registration before validation. Allows plugins to modify the user model (e.g., set custom fields, modify data) before it's validated and saved.

function: Hooks¶

Function hooks allow plugins to modify the behavior of helper functions.

function:format_text
- Location: vendor/traq/helpers/formatting.php
- Parameters: &$text (text string, passed by reference), $strip_html (boolean)
- Description: Called within the format_text() helper function. Allows plugins to process or modify text formatting before it's displayed. Commonly used by formatting plugins (e.g., Markdown, BBCode) to convert text to HTML.
function:ticket_filters
- Location: vendor/traq/helpers/tickets.php
- Parameters: &$filters (array of filter options, passed by reference)
- Description: Called within the ticket_filters() helper function. Allows plugins to add custom filter options to the ticket filtering system.

use:plugins: Hooks¶

Plugin-to-plugin hooks allow plugins to expose functionality to other plugins.

use:plugins:security_questions.question_field
- Location: vendor/traq/plugins/security_questions/security_questions.php
- Parameters: Varies (see Security Questions plugin documentation)
- Description: Exposed by the Security Questions plugin. Allows other plugins to retrieve or display security question fields. Check the Security Questions plugin documentation for parameter details.
use:plugins:security_questions.check_answer
- Location: vendor/traq/plugins/security_questions/security_questions.php
- Parameters: Varies (see Security Questions plugin documentation)
- Description: Exposed by the Security Questions plugin. Allows other plugins to validate security question answers. Check the Security Questions plugin documentation for parameter details.

Usage Examples¶

Registering a Hook¶

Hooks are registered in your plugin's init() method using FishHook::add(). The first parameter is the hook name, and the second is a callable (typically an array with the class name and method name).

use \FishHook;

public static function init()
{
    // Template hook
    FishHook::add('template:users/register', array(get_called_class(), 'my_method'));

    // Controller hook
    FishHook::add('controller:users.register', array(get_called_class(), 'my_controller_method'));

    // Function hook
    FishHook::add('function:format_text', array(get_called_class(), 'my_format_method'));
}

Hook Method Signatures¶

The method signature for your hook handler depends on the hook type and the parameters it provides.

Template Hooks¶

Template hooks output HTML directly using echo or print. Parameters are optional and depend on the specific hook.

// Template hook with no parameters
public static function my_template_hook()
{
    echo '<div>My content</div>';
}

// Template hook with optional parameters
public static function my_template_hook($project)
{
    if ($project) {
        echo '<div>Project: ' . htmlspecialchars($project->name) . '</div>';
    }
}

// Template hook with required parameters
public static function my_user_nav_hook($user)
{
    echo '<li><a href="/custom">Custom Link</a></li>';
}

Controller Hooks¶

Controller hooks receive parameters by reference, allowing you to modify them before they're used by the core code.

// Controller hook (parameters passed by reference)
public static function my_controller_hook(&$user)
{
    // Modify $user before validation
    $user->set('custom_field', 'value');
}

Function Hooks¶

Function hooks also receive parameters by reference, allowing you to modify the data before it's returned or used.

// Function hook (parameters passed by reference)
public static function my_function_hook(&$text, $strip_html)
{
    // Modify $text before it's processed
    $text = strtoupper($text);
}

// Function hook for ticket filters
public static function my_ticket_filters_hook(&$filters)
{
    // Add custom filter options
    $filters['custom_field'] = 'Custom Filter';
}

Notes¶

Registration: Hooks are registered using FishHook::add() in the plugin's init() method
Execution: Hooks are executed using FishHook::run() in the core code
Reference Parameters: Parameters passed by reference (&$param) can be modified by the hook
Template Output: Template hooks typically output HTML directly using echo or print
Data Modification: Controller and function hooks can modify data before it's used by the core code
Hook Order: Multiple plugins can register hooks for the same event; they will be executed in the order they were registered
Error Handling: If a hook method throws an exception, it may prevent subsequent hooks from executing