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.

System Registry

The purpose of the registry is to store key-value pairs of information. It can be considered an equivalent to the Windows registry (only not as complicated).

You might use the registry to hold information that your script needs to store across sessions or requests.

An example would be a setting that needs to be altered by a PHP script, which currently is not possible with TypoScript.

Another example: The Scheduler system extension stores when it ran the last time. The Reports system extension then checks that value, in case it determines that the Scheduler hasn't run for a while, it issues a warning. While this might not be of much use to someone who has set up an actual cron job for the Scheduler, but it is useful for users who need to run the Scheduler tasks manually due to a lack of access to a cron job.

The registry is not intended to store things that are supposed to go into a session or a cache, use the appropriate API for them instead.

The Registry Table (sys_registry)

Here's a description of the fields that can be found in the sys_registry table:

Field	Type	Description
uid	int	Primary key, needed for replication and also useful as an index.
entry_namespace	varchar (128)	Represents an entry's namespace. In general, the namespace is an extension key starting with tx_, a user script's prefix user_, or core for entries that belong to the core. The purpose of namespaces is that entries with the same key can exist within different namespaces.
entry_key	varchar (255)	The entry's key. Together with the namespace, the key is unique for the whole table. The key can be any string to identify the entry. It's recommended to use dots as dividers if necessary. In this way, the naming is similar to the syntax already known in TypoScript.
entry_value	blob	The entry's actual value. The value is stored as a serialized string, thus you can even store arrays or objects in a registry entry – it's not recommended though. Using phpMyAdmin's Show BLOB option allows you to check the value in this field even though it is stored as a binary.

The Registry API

There is an easy-to-use API for using the registry. Simply call the following code to retrieve an instance of the registry. The instance returned will always be the same, as the registry is a singleton:

$registry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Registry::class);

After retrieving an instance of the registry, you can access the registry values through its get() method. The get() method provides an interesting third parameter to specify a default value that is returned if the requested entry is not found in the registry. This happens, for example, the first time an entry is accessed. Setting a value is also easy with the set() method.

Method	Parameters	Description
set	$namespace : namespace in which the value to set $key : the key of the value to set $value : the value to store	Represents an entry's namespace. In general, the namespace is an extension key that starts with tx_, a user script's prefix user_, or core for entries that belong to the core.
get	$namespace : namespace from which the value is to be obtained $key : the key of the value to be retrieved $defaultValue : a default value if the key was not found in the given namespace	Used to get a value from the registry.
remove	$namespace : namespace from which the value is to be removed $key : the key of the value to be removed	Remove an entry from a given namespace.
removeAllByNamespace	$namespace : namespace to be emptied	Deletes all values for a given namespace.

Note

Do not store binary data in the registry, it it not intended for this purpose. Use the file system instead, if you have such needs.

Examples

Here's an example taken from the Scheduler system extension:

$context = GeneralUtility::makeInstance(Context::class);
$requestStartTimestamp = $context->getPropertyFromAspect('date', 'timestamp');
$registry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Registry::class);
$runInformation = array('start' => $requestStartTimestamp, 'end' => time(), 'type' => $type);
$registry->set('tx_scheduler', 'lastRun', $runInformation);

It is retrieved later using:

$registry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Registry::class);
$lastRun = $registry->get('tx_scheduler', 'lastRun');