Hooks

Using hooks

The two lines of code below are an example of how a hook can be used for clear-cache post-processing. The objective of this could be to perform additional actions whenever the cache is cleared for a specific page:

<?php

declare(strict_types=1);

use MyVendor\MyExtension\Hook\DataHandlerHook;

defined('TYPO3') or die();

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['clearCachePostProc'][] =
    DataHandlerHook::class . '->postProcessClearCache';

This hook registers the class/method name to a hook inside of \TYPO3\CMS\Core\DataHandling\DataHandler . The hook calls the user function after the cache has been cleared. The user function will receive parameters which allows it to see what clear-cache action was performed and typically also an object reference to the parent object. Then the user function can take additional actions as needed.

The class has to follow the PSR-4 class name scheme to be available in autoloading.

If we take a look inside of \TYPO3\CMS\Core\DataHandling\DataHandler we find the hook to be activated like this:

<?php

namespace TYPO3\CMS\Core\DataHandling;

use TYPO3\CMS\Core\Utility\GeneralUtility;

class DataHandler
{
    protected function prepareCacheFlush($table, $uid, $pid)
    {
        // do something [...]
        // Call post processing function for clear-cache:
        $_params = ['table' => $table, 'uid' => $uid/*...*/];
        foreach ($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['clearCachePostProc'] ?? [] as $_funcRef) {
            GeneralUtility::callUserFunction($_funcRef, $_params, $this);
        }
    }
}

This is how hooks are typically constructed. The main action happens in line 5 where the function \TYPO3\CMS\Core\Utility\GeneralUtility::callUserFunction() is called. The user function is called with two arguments, an array with variable parameters and the parent object.

In line 24 the content of the parameter array is prepared. This is of high interest to you because this is where you see what data is passed to you and what data might be passed by reference and thereby could be manipulated from your hook function.

Finally, notice how the array $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['clearCachePostProc'] is traversed and for each entry the value is expected to be a function reference which will be called. This allows many hooks to be called at once. The hooks can even rearrange the calling order if they dare.

The syntax of a function reference can be seen in the API documentation of \TYPO3\CMS\Core\Utility\GeneralUtility .

Creating hooks

There are two main methods of calling a user-defined function in TYPO3.

\TYPO3\CMS\Core\Utility\GeneralUtility::callUserFunction()

Takes a reference to a function in a PHP class reference as value and calls that function. The argument list is fixed to a parameter array and a parent object.

\TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance()

Creates an object from a user-defined PHP class. The method to be called is defined by the implementation of the hook.

Here are some examples:

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension;

use TYPO3\CMS\Core\Utility\GeneralUtility;

final class SomeClass
{
    public function doSomeThing(): void
    {
        // Hook for processing data submission to extensions
        foreach ($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['my_custom_hook']
                 ['checkDataSubmission'] ?? [] as $className) {
            $_procObj = GeneralUtility::makeInstance($className);
            $_procObj->checkDataSubmission($this);
        }
    }
}

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension;

use TYPO3\CMS\Core\Utility\GeneralUtility;

final class SomeClass
{
    public function doSomeThing(): void
    {
        // Call post-processing function for constructor:
        if (is_array($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS'][self::class]['Some-PostProc'])) {
            $_params = ['pObj' => &$this];
            foreach ($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS'][self::class]['Some-PostProc'] as $_funcRef) {
                GeneralUtility::callUserFunction($_funcRef, $_params, $this);
            }
        }
    }
}

Hook configuration

Most hooks in the TYPO3 Core have been converted into PSR-14 events which are completely listed in the event list.

There is no complete index of the remaining hooks in the Core. The following naming scheme should be used:

<?php

declare(strict_types=1);

defined('TYPO3') or die();

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['<extension_key>']['<sub_key>'] = '<value>';

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']

Configuration space for Core extensions.

This array is created as an ad hoc space for creating hooks from any script. This will typically be used from the Core scripts of TYPO3 which do not have a natural identifier like extensions have their extension keys.

<?php

declare(strict_types=1);

defined('TYPO3') or die();

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['<extension_key>']['<sub_key>'] = '<value>';

<main_key>

The relative path of a script (for output scripts it should be the "script ID" as found in a comment in the HTML header)

<sub_key>

This is defined by the script. Typically it identifies the context of the hook.

<index>

Integer index typically. Can be a unique string, if you have a reason to use that. Normally it has no greater significance since the value of the key is not used. The hooks normally traverse over the array and uses only the value (function reference).

<function_reference>

A function reference using the syntax of \TYPO3\CMS\Core\Utility\GeneralUtility::callUserFunction() as a function or \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance() as a class name depending on implementation of the hook.

A namespace function has the format \Foo\Bar\MyClassName::class . '->myUserFunction'.

A namespace class should be used in the unquoted form, for example \Foo\Bar\MyClassName::class. The called function name is determined by the hook itself.

The above syntax is how a hook is typically defined but it might differ and it might not be a hook at all, but just configuration. Depends on implementation in any case.