Hooks

Hooks are similar to filters and actions in WordPress.

Hooks allow plugins, themes, and third-party code to intervene in the application and make modifications. Anyone can create a hook.

use PKP\plugins\Hook;

Hook::call('Context::delete', [$context]);

Add a callback function to fire when the hook is called. The example below sends an email whenever a journal, press or pre-print server is deleted.

use Illuminate\Support\Facades\Mail;
use PKP\mail\Mailable;
use PKP\plugins\Hook;

Hook::add('Context::delete', function($hookName, $args) {
    $context = $args[0];

    $mailable = new Mailable();
    $mailable->to('admin@example.com')
        ->from('editor@example.com')
        ->subject('The journal ' . $context->getLocalizedName() . ' was deleted.');

    Mail::send($mailable);

    return false;
});

It’s also possible to use a hook to modify data. In the example below, every new journal that is created is assigned a default publisherInstitution.

use PKP\plugins\Hook;

Hook::add('Context::add', function($hookName, $args) {
    $context = $args[0];

    $context->setData('publisherInstitution', 'Public Knowledge Project');

    return false;
});

Pass primitive types into hooks by reference (&). For example, a string, integer or boolean must be passed to the hook by reference in order for a callback function to be able to modify it.

$xml = '<xml ...>';
Hook::call('Deposit::xml', [&$xml]);

Hook::add('Deposit::xml', function($hookName, $args) {
    $xml =& $args[0];

    // $xml is now a reference to the same string instead of a copy
    // so changes made here will effect the original variable

    return false;
});

More than one callback can be registered to each hook. They are fired in the order that they were registered. Pass a hook priority constant (HOOK_SEQUENCE_...) to make the hook fire earlier or later in the queue.

Hook::add('Crossref::deposit', function($hookName, $args) {
    // ...

    return false;
}, HOOK_SEQUENCE_LATE);

Return a truthy value from the callback function to prevent other callbacks from running.

Hook::add('Crossref::deposit', function($hookName, $args) {
    return true;
}, HOOK_SEQUENCE_CORE);

Hook names should begin with a namespace for the entity or task it effects and use :: to separate it from the action. Some examples

Context::add
Context::edit
Context::validate
Context::delete
Request::getBaseUrl
Dispatcher::dispatch
APIHandler::endpoints

Plugins #

Hooks are most commonly used in generic plugins. Calling hooks from other types of plugins may not work. The plugin guide includes some examples that use hooks.

Common Hooks #

This is an incomplete list. Search the application code for HookRegistry::call to get a complete list of hooks available in OJS 3.4.

Request, Routing and Templating #

The following hooks allow plugins to intervene in request handling and routing. They make it possible to divert a request to a custom handler, override request parameters, and effect which params are supported by an API endpoint.

Entities #

The following hooks allow plugins to intervene in how Entities are fetched, validated, added and edited. Use these hooks to modify the properties of an object.

The hooks in the list below are available for any entity that has been converted to a schema and service class.

Some entities provide hooks for additional actions taken in the Repository class.

The hooks in the list below are available for any entity that has not been converted to the schema and service class. These entities use a DAO to define the properties of the model.

Components #

The following hooks allow plugins to intervene in the data passed to UI components. These hooks are only available for components in the UI Library.