Attention

TYPO3 v9 has reached its end-of-life September 30th, 2021 and is not maintained by the community anymore. Looking for a stable version? Use the version switch on the top left.

You can order Extended Long Term Support (ELTS) here: TYPO3 ELTS.

The Concept of "Hooks" and "Signals"

Hooks and Signals provide an easy way to extend the functionality of TYPO3 and its extensions without blocking others to do the same. Hooks are basically places in the source code where a user function will be called for processing if such has been configured. Signals roughly follow the observer pattern. Signals and slots decouple the sender (sending a signal) and the receiver(s) (called slots). The sender sends a signal - like "database updated" - and all receivers listening to that signal will be executed.

Hooks and Signals vs. XCLASS Extensions

Hooks or Signals are the recommended way of extending TYPO3 compared to extending PHP classes with a child class (see "XCLASS extensions"). Because only one extension of a PHP class can exist at a time while hooks and signals may allow many different user-designed processor functions to be executed. However, hooks and signals have to be implemented in the TYPO3 core before you can use them, while extending a PHP class via the XCLASS method allows you to extend any class you like.

Proposing Hooks or Signals

If you need to extend something which has no hook or signal yet, then you should suggest implementing one. Normally that is rather easily done by the author of the source you want to extend.

Using Hooks

The two lines of code below are an example of how a hook is 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.

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

This registers the class/method name to a hook inside of \TYPO3\CMS\Core\DataHandling\DataHandler. The hook will call the user function after the clear-cache command has been executed. 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 be declared with the TYPO3 autoloader.

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

1   // Call post processing function for clear-cache:
2if (is_array($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['clearCachePostProc'])) {
3   $_params = array('cacheCmd' => $cacheCmd);
4   foreach($GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['clearCachePostProc'] as $_funcRef) {
5      \TYPO3\CMS\Core\Utility\GeneralUtility::callUserFunction($_funcRef, $_params, $this);
6   }
7}

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 3 the contents 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 possibly be passed by reference and thereby possible to manipulate 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 the same place. 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.

Note

The example hook shown above refers to old class names. All these old class names were left in hooks, for obvious reasons of backwards-compatibility.

Using Signals

To connect a slot to a signal, use the \TYPO3\CMS\Extbase\SignalSlot\Dispatcher::connect() method. This method accepts the following arguments:

  1. $signalClassName: Name of the class containing the signal

  2. $signalName: Name of the class containing the signal

  3. $slotClassNameOrObject: Name of the class containing the slot or the instantiated class or a \Closure object

  4. $slotMethodName: Name of the method to be used as a slot. If $slotClassNameOrObject is a \Closure object, this parameter is ignored and can be skipped

  5. $passSignalInformation: If set to true, the last argument passed to the slot will be information about the signal (EmitterClassName::signalName)

Usage example:

1$signalSlotDispatcher = \TYPO3\CMS\Core\Utility\GeneralUtility::
2   makeInstance(\TYPO3\CMS\Extbase\SignalSlot\Dispatcher::class);
3$signalSlotDispatcher->connect(
4  \TYPO3\CMS\Extensionmanager\Utility\InstallUtility::class,  // Signal class name
5  'afterExtensionUninstall',                                  // Signal name
6  \TYPO3\CMS\Core\Core\ClassLoadingInformation::class,        // Slot class name
7  'dumpClassLoadingInformation'                               // Slot name
8);

In this example, we define that we want to call the method dumpClassLoadingInformation of the class \TYPO3\CMS\Core\Core\ClassLoadingInformation::class when the signal afterExtensionUninstall of the class \TYPO3\CMS\Extensionmanager\Utility\InstallUtility::class is dispatched.

To find out which parameters/variables are available, open the signal's class and take a look at the dispatch call:

$this->signalSlotDispatcher->dispatch(__CLASS__, 'afterExtensionUninstall', [$extensionKey, $this]);

In this case, the dumpClassLoadingInformation method will get the extension key and an instance of the dispatching class as parameters.

Finding Signals

There is no complete list of signals available, but they are easily found by searching the TYPO3 core for dispatch(.

For finding hooks, look into the next chapter Hook Configuration.