Class FileLockEngine
File-based lock engine using flock().
This engine uses PHP's flock() function for locking, which provides advisory locking on the filesystem. This is suitable for single-server deployments but NOT for distributed systems.
Note: This engine does not support TTL-based automatic expiration. Locks are held until explicitly released, the acquired lock is destroyed, or the process terminates. A cleanup mechanism is provided for stale lock files.
Configuration options:
path: Directory path for lock files (default: system temp directory)prefix: Prefix for lock file names (default: 'lock_')ttl: Default TTL for stale file cleanup (default: 300)
Property Summary
-
$_config protected
array<string, mixed>Runtime config
-
$_configInitialized protected
boolWhether the config property has already been configured with defaults
-
$_defaultConfig protected
array<string, mixed>Default configuration.
-
$_handles protected
array<string, resource>Active lock file handles.
Method Summary
-
__destruct() public
Destructor to clean up open handles.
-
_configDelete() protected
Deletes a single config key.
-
_configRead() protected
Reads a config key.
-
_configWrite() protected
Writes a config key.
-
acquire() public
Acquire a lock for the given resource.
-
acquireBlocking() public
Acquire a lock, waiting up to $timeout seconds if necessary.
-
cleanupStaleLock() protected
Clean up a stale lock file if it's older than TTL.
-
configShallow() public
Merge provided config with existing config. Unlike
config()which does a recursive merge for nested keys, this method does a simple merge. -
deleteConfig() public
Deletes a config key.
-
ensureValidResource() protected
Ensure the resource identifier is valid.
-
forceRelease() public
Force release a lock without ownership verification.
-
generateToken() protected
Generate a unique token for lock ownership.
-
getConfig() public
Returns the config.
-
getConfigOrFail() public
Returns the config for this specific key.
-
getLockFile() protected
Get the file path for a lock.
-
init() public
Initialize the file lock engine.
-
isLocked() public
Check if a resource is currently locked.
-
key() protected
Generate the full key for a resource.
-
refresh() public
Refresh a lock's TTL.
-
release() public
Release a lock.
-
setConfig() public
Sets the config.
Method Detail
_configDelete() ¶ protected
_configDelete(string $key): voidDeletes a single config key.
Parameters
-
string$key Key to delete.
Returns
voidThrows
Cake\Core\Exception\CakeExceptionif attempting to clobber existing config
_configRead() ¶ protected
_configRead(string|null $key): $key is null ? array : mixedReads a config key.
Parameters
-
string|null$key Key to read.
Returns
$key is null ? array : mixed_configWrite() ¶ protected
_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): voidWrites a config key.
Parameters
-
array<string, mixed>|string$key Key to write to.
-
mixed$value Value to write.
-
string|bool$merge optional True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
Returns
voidThrows
Cake\Core\Exception\CakeExceptionif attempting to clobber existing config
acquire() ¶ public
acquire(string $resource, int $ttl = 300): Cake\Lock\AcquiredLock|nullAcquire a lock for the given resource.
Uses flock() with LOCK_EX | LOCK_NB for non-blocking exclusive lock.
Parameters
-
string$resource The resource identifier to lock.
-
int$ttl optional Time-to-live in seconds (used for stale file cleanup).
Returns
Cake\Lock\AcquiredLock|nullReturns an AcquiredLock on success, null on failure.
acquireBlocking() ¶ public
acquireBlocking(string $resource, int $ttl = 300, int $timeout = 10, int $retryInterval = 100): Cake\Lock\AcquiredLock|nullAcquire a lock, waiting up to $timeout seconds if necessary.
This is a default blocking implementation that repeatedly attempts to acquire the lock. Engines may override this with more efficient implementations.
Parameters
-
string$resource The resource identifier to lock.
-
int$ttl optional Time-to-live in seconds for the lock.
-
int$timeout optional Maximum time in seconds to wait for the lock.
-
int$retryInterval optional Milliseconds to wait between retry attempts.
Returns
Cake\Lock\AcquiredLock|nullReturns an AcquiredLock on success, null on timeout.
cleanupStaleLock() ¶ protected
cleanupStaleLock(string $file, int $ttl): voidClean up a stale lock file if it's older than TTL.
Parameters
-
string$file The lock file path.
-
int$ttl TTL in seconds.
Returns
voidconfigShallow() ¶ public
configShallow(array<string, mixed>|string $key, mixed|null $value = null): $thisMerge provided config with existing config. Unlike config() which does
a recursive merge for nested keys, this method does a simple merge.
Setting a specific value:
$this->configShallow('key', $value);Setting a nested value:
$this->configShallow('some.nested.key', $value);Updating multiple config settings at the same time:
$this->configShallow(['one' => 'value', 'another' => 'value']);Parameters
-
array<string, mixed>|string$key The key to set, or a complete array of configs.
-
mixed|null$value optional The value to set.
Returns
$thisdeleteConfig() ¶ public
deleteConfig(string $key): $thisDeletes a config key.
Parameters
-
string$key Key to delete. It can be a dot separated string to delete nested keys.
Returns
$thisensureValidResource() ¶ protected
ensureValidResource(string $resource): voidEnsure the resource identifier is valid.
Parameters
-
string$resource The resource to validate.
Returns
voidThrows
Cake\Lock\Exception\InvalidArgumentExceptionIf resource is invalid.
forceRelease() ¶ public
forceRelease(string $resource): boolForce release a lock without ownership verification.
WARNING: This should only be used for administrative purposes as it bypasses owner verification and may cause race conditions.
Parameters
-
string$resource The resource identifier to force release.
Returns
boolTrue if the lock was released, false otherwise.
generateToken() ¶ protected
generateToken(): stringGenerate a unique token for lock ownership.
Returns
stringA unique token string.
getConfig() ¶ public
getConfig(string|null $key = null, mixed $default = null): $key is null ? array : mixedReturns the config.
Usage
Reading the whole config:
$this->getConfig();Reading a specific value:
$this->getConfig('key');Reading a nested value:
$this->getConfig('some.nested.key');Reading with default value:
$this->getConfig('some-key', 'default-value');Parameters
-
string|null$key optional The key to get or null for the whole config.
-
mixed$default optional The return value when the key does not exist.
Returns
$key is null ? array : mixedConfiguration data at the named key or null if the key does not exist.
getConfigOrFail() ¶ public
getConfigOrFail(string $key): mixedReturns the config for this specific key.
The config value for this key must exist, it can never be null.
Parameters
-
string$key The key to get.
Returns
mixedConfiguration data at the named key
Throws
InvalidArgumentExceptiongetLockFile() ¶ protected
getLockFile(string $resource): stringGet the file path for a lock.
Parameters
-
string$resource The resource identifier.
Returns
stringThe lock file path.
init() ¶ public
init(array<string, mixed> $config = []): boolInitialize the file lock engine.
Parameters
-
array<string, mixed>$config optional Configuration options.
Returns
boolTrue if initialization was successful.
isLocked() ¶ public
isLocked(string $resource): boolCheck if a resource is currently locked.
Note: This is a point-in-time check and the lock status may change immediately after this method returns.
Parameters
-
string$resource The resource identifier to check.
Returns
boolTrue if the resource is locked, false otherwise.
key() ¶ protected
key(string $resource): stringGenerate the full key for a resource.
Parameters
-
string$resource The resource identifier.
Returns
stringThe prefixed key.
Throws
Cake\Lock\Exception\InvalidArgumentExceptionIf resource is invalid.
refresh() ¶ public
refresh(Cake\Lock\AcquiredLock $lock, int|null $ttl = null): boolRefresh a lock's TTL.
Updates the lock file's metadata with a new TTL.
Parameters
-
Cake\Lock\AcquiredLock$lock The lock instance to refresh.
-
int|null$ttl optional New TTL in seconds. If null, uses the original TTL.
Returns
boolTrue if the lock was refreshed, false otherwise.
release() ¶ public
release(Cake\Lock\AcquiredLock $lock): boolRelease a lock.
Parameters
-
Cake\Lock\AcquiredLock$lock The lock instance to release.
Returns
boolTrue if the lock was released, false otherwise.
setConfig() ¶ public
setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $thisSets the config.
Usage
Setting a specific value:
$this->setConfig('key', $value);Setting a nested value:
$this->setConfig('some.nested.key', $value);Updating multiple config settings at the same time:
$this->setConfig(['one' => 'value', 'another' => 'value']);Parameters
-
array<string, mixed>|string$key The key to set, or a complete array of configs.
-
mixed|null$value optional The value to set.
-
bool$merge optional Whether to recursively merge or overwrite existing config, defaults to true.
Returns
$thisThrows
Cake\Core\Exception\CakeExceptionWhen trying to set a key that is invalid.
Property Detail
$_configInitialized ¶ protected
Whether the config property has already been configured with defaults
Type
bool$_defaultConfig ¶ protected
Default configuration.
prefix: Prefix for all lock keys. Useful for namespacing.ttl: Default time-to-live in seconds for locks.
Type
array<string, mixed>