Hooks

Hooks allow executing code and modifying data at predefined places by registering them with callback functions.

#Overview

There are two types of hooks available:

• Filters

  Receive, modify and return data back to the calling hook. Can be used to modify the page title and metatags, override specific user permissions, add or remove CSS and scripts from the page, etc.

• Actions

  Receive data, execute code, and return nothing. Can be used to run code at specific points in the request and echo output at pre-defined places in templates.

Find can find a list of available hooks in the Hooks Directory

#Getting Started

To use a hook, it's necessary to register a hook callback function using the hook name. The callback function is executed by the hook system and receives data, in the case of filters, along with parameters. Filter callback functions must always return the data back to the originating hook.

To get started, create the hooks.php file in overrides:

Joomla

templates/jreviews_overrides/hooks.php

WordPress

jreviews_overrides/hooks.php

The file needs to begin with the following code:

<?php
defined('MVC_FRAMEWORK') or die;

Now you can register all your hook callbacks directly in this file, or organize them into different files as explained at the end of this article.

To register a Filter Hook you can use function closures with the fwd_add_filter helper function:

fwd_add_filter('filter_name', function($data, $params)
{
  // Modify the $data and return it
  return $data;
});

Or, create a named function, and then add the function name to the callback parameter:

function filter_callback($data, $params = [])
{
   // Modify the $data and return it
   return $data;
}

fwd_add_filter('filter_name', 'filter_callback');

Named functions can come in handy, when you can use the same callback function for several hooks.

Registering an Action Hook is similar using the fwd_add_action helper function, but nothing is returned from inside the function.

fwd_add_action('action_name', function($params)
{
  // Execute some action or echo some output
});

You can optionally specify a priority (default is 20, lower numbers execute earlier):

fwd_add_filter('filter_name', function($data, $params)
{
  return $data;
}, $priority = 10);

#Examples & Tutorials

You can find examples to use in the Hooks Directory, and also within the JReviews and Add-ons source code. In JReviews you can look in the following directories.

Joomla

components/com_jreviews/jreviews/filters/
components/com_jreviews/jreviews/plugins/

WordPress

wp-content/plugins/jreviews/jreviews/filters/
wp-content/plugins/jreviews/jreviews/plugins/

You can also find development tutorials in our blog:

• How to create your own profanity and spam blocker

The TrustedUsers Add-ons is also a fine example because it is developed entirely using hooks.

#Migrating from JReviews 5

If you're upgrading from JReviews 5, there are two main changes to the hooks system in version 6:

#File Location Change

JReviews 5:

• File: jreviews_overrides/filters/filter_functions.php

JReviews 6:

• File: jreviews_overrides/hooks.php

#Syntax Change

The hook registration syntax has changed from the Clickfwd Hook classes to user-friendly helper functions.

JReviews 5 (Old):

// Filter hook
Clickfwd\Hook\Filter::add('filter_name', function($data, $params) {
    return $data;
}, $priority = 10);

// Action hook
Clickfwd\Hook\Action::add('action_name', function($params) {
    // Execute action
}, $priority = 10);

JReviews 6 (New):

// Filter hook
fwd_add_filter('filter_name', function($data, $params) {
    return $data;
});

// Action hook
fwd_add_action('action_name', function($params) {
    // Execute action
});

#Organizing Hooks

If you plan on using a lot of hooks on your site, one way to organizing them is to create a file per hook, and then include that file from within hooks.php.

jreviews_overrides/hooks.php
jreviews_overrides/hooks/hook_one.php
jreviews_overrides/hooks/hook_two.php
jreviews_overrides/hooks/hook_three.php

In hooks.php

<?php
defined('MVC_FRAMEWORK') or die;

require_once __DIR__ . '/hooks/hook_one.php';

require_once __DIR__ . '/hooks/hook_two.php';

require_once __DIR__ . '/hooks/hook_three.php';