README

English | 中文

A flexible distributed lock service bundle for Symfony, supporting Redis Cluster, database, and file-based backends. Ideal for resource mutual exclusion and synchronization in high concurrency scenarios.

Features

Supports Redis Cluster, database, and file lock backends
SmartLockStore for automatic backend switching
Provides read/write locks, blocking locks, and multi-resource locking
Seamless integration with Symfony ecosystem
Easy to extend and customize

Requirements

PHP >= 8.1
Symfony >= 6.4
Redis, database, or file backend configured

Installation

Composer

composer require tourze/lock-service-bundle

Quick Start

use Tourze\LockServiceBundle\Service\LockService;

$lockService = ... // Get via dependency injection

// Blocking execution
$lockService->blockingRun('resource-key', function () {
    // Logic protected by lock
});

// Multi-resource locking
$lockService->blockingRun(['key1', 'key2'], function () {
    // Logic protected by multiple locks
});

Configuration

Bundle Registration

Add to your bundles.php:

return [
    // ... other bundles
    Tourze\LockServiceBundle\LockServiceBundle::class => ['all' => true],
];

Environment Configuration

Select lock type via APP_LOCK_TYPE environment variable:

redis
redis-cluster
dbal
flock

Example:

APP_LOCK_TYPE=redis

Database Configuration

If using DBAL backend, the bundle automatically configures a dedicated lock connection with SQLite for testing. For production, configure your database connection in doctrine.yaml:

doctrine:
    dbal:
        connections:
            lock:
                driver: pdo_mysql
                host: '%database_host%'
                port: '%database_port%'
                dbname: '%database_name%'
                user: '%database_user%'
                password: '%database_password%'

Advanced Usage

Automatic backend switching via SmartLockStore
Retry and wait mechanism for lock acquisition
Read/write lock support (see RedisClusterStore)
Extensible: implement LockEntity interface for custom lock resources

Entity Design

This bundle provides a LockEntity interface for defining lock resources:

interface LockEntity {
    public function retrieveLockResource(): string;
}

Implement this interface for your business entities to enable fine-grained distributed locking.

Security

This bundle provides secure distributed locking mechanisms:

Thread-safe lock acquisition and release
Automatic lock expiration to prevent deadlocks
Resource isolation through unique lock keys
Protection against race conditions in concurrent environments

Security Considerations

Use unique, unpredictable lock keys for sensitive resources
Set appropriate lock timeouts to prevent resource starvation
Monitor lock usage to detect potential abuse
Use dedicated Redis/database instances for production environments

Contributing

Please see CONTRIBUTING.md for details. Follow PSR standards and provide tests.

License

MIT License

Changelog

See CHANGELOG.md

tourze / lock-service-bundle

Maintainers

Details