Download the PHP package b13/distributed-locks without Composer

Distributed Redis Locker for TYPO3 Locking Mechanism

TYPO3 has three built-in Locking Strategies, that are chosen at runtime which fits best for the current system setup.

• SemaphoreLockStrategy
• SimpleLockStrategy
• FileLockStrategy

However, when dealing with a multi-tier system and a shared file system with multiple frontend nodes with a NFS filesystem, it is especially helpful to use a better suitable format. Redis is our weapon of choice for handling multi-node scenarios, and works just fine with TYPO3 and Caching.

This extension provides a Redis Locking mechanism to store the locks in a (shared) Redis database.

Requirements

This extension supports TYPO3 v12.4, v13.4 and v14.3. It requires PHP 8.1+, the PHP extension php-redis, and a Redis server.

Installation

Install this extension via composer composer require b13/distributed-locks or extensions.typo3.org / Extension Manager, and activate it in the Extension Manager.

Now add the following lines to config/system/additional.php to activate Redis Locking.

$GLOBALS['TYPO3_CONF_VARS']['SYS']['locking']['redis'] = [
    'hostname' => '127.0.0.1',
    'database' => 12
];

Other options:

'ttl' (numeric, default is 30sec)
'port' (numeric, default is 6379)
'password' (contains the password, necessary for secure authentication if required by redis)
'username' (contains an username, if required by redis)
'priority' (numeric, default is 95) - Set priority for this locking strategy. See LockingApi documentation.
'connectionTimeout' (numeric, default is 0.0 = no timeout) - Seconds to wait for the connection to the redis server.
'persistentConnection' (boolean, default is false) - Use a persistent connection to the redis server.
'gracefulDegradation' (boolean, default is true) - Keep the site running if redis is unavailable, see below.
'fallbackStrategy' (class name, default is TYPO3\CMS\Core\Locking\FileLockStrategy) - Locking strategy to
    use while redis is unavailable. Set to null to run without any locking in that case.

Behaviour when the redis server is unavailable

The connection to redis is established when a lock is created. If the redis server is down, this throws a RedisException ("Connection refused"), and since TYPO3's LockFactory neither catches exceptions nor falls back to another strategy, a redis outage would take down the whole frontend with a 503 error.

For this reason the locking strategy degrades gracefully by default: the failure is logged (log level "critical"), and this lock - plus all further locks of the same PHP process - is handled by the fallbackStrategy, by default TYPO3's FileLockStrategy. The redis server is contacted again after 30 seconds at the earliest, so a request does not run into the connection timeout for every single lock. The same happens if the connection breaks while a request is running.

If fallbackStrategy is set to null, locking is skipped entirely while redis is unavailable. The site keeps working, but the same page may be generated by several processes in parallel.

If you prefer the previous behaviour - an exception instead of a fallback - switch it off:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['locking']['redis']['gracefulDegradation'] = false;

Disabling it in certain contextes

If you have different TYPO3_CONTEXT or environments and you want to switch off the complete redis strategy (i.e. in your staging machine), you can set this in config/system/additional.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['locking']['redis']['disabled'] = true;

Future Development

Should be switched to symfony/lock to allow distributed redis services and other lockers.

Credits & Background

Inspiration was taken from the now unmaintained extension "redis_lock_strategy" which we used several times, however with some drawbacks:

• No stable version for TYPO3 v9 in composer mode
• No maintainer available for releases anymore
• Destroying an object did not remove locks, ending in certain dead lock scenarios in broken scripts

Thanks to Alexander Miehe for the initial extension and the conceptual work.

Sharing our expertise

Find more TYPO3 extensions we have developed that help us deliver value in client projects. As part of the way we work, we focus on testing and best practices to ensure long-term performance, reliability, and results in all our code.