Using the system registry

The purpose of the registry (introduced in TYPO3 4.3) is to hold key- value pairs of information. You can actually think of it being an equivalent to the Windows registry (just not as complicated).

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

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 great use to anyone with an actual cron job set up for the scheduler, it is of use for users that have to run the scheduler tasks by hand due to missing access to a cron job.

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

The registry table (sys_registry)

Here's a description of the fields 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 point of namespaces is that entries with the same key can exist inside 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. This way the naming is similar to the already known syntax 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 you can check the value in that field although being stored as a binary.

The registry API

To use the registry, there's an easy to use API. Simply use the code below 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');

After retrieving an instance of the registry you can access the registry values through its get() method. The get() method offers an interesting third parameter to specify a default value, that value is returned in case the requested entry was not found in the registry. That happens when accessing an entry for the first time for example. Setting a value is easy as well using the set() method.

Method Parameters Description
set

$namespace : namespace in which to set the value

$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 starting with "tx_", a user script's prefix "user_", or "core" for entries that belong to the core.
get

$namespace : namespace to get the value from

$key : the key of the value to retrieve

$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 to remove the value from

$key : the key of the value to remove

Remove an entry from a given namespace.
removeAllByNamespace $namespace : namespace to empty Deletes all value for a given namespace.

Note that you should not store binary data into the registry, it's not designed to do that. Use the filesystem instead, if you have such needs.

Examples

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

$registry = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance('TYPO3\\CMS\\Core\\Registry');
$runInformation = array('start' => $GLOBALS['EXEC_TIME'], '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');
$lastRun = $registry->get('tx_scheduler', 'lastRun');