README

English | 中文

A lightweight Symfony bundle providing declarative distributed locking based on AOP (Aspect-Oriented Programming). Easily add locking logic to your methods using attributes, enabling safe concurrency control in distributed environments.

Features

Declarative locking with the #[Lockable] attribute
Customizable lock key with Twig template syntax
Automatic lock acquire/release (even on exception)
Seamless integration with Symfony Lock component
Suitable for distributed/multi-instance deployments

Installation

Requirements:

PHP >= 8.1
Symfony >= 6.4
Required dependencies: symfony/lock, twig/twig, tourze/symfony-aop-bundle

Install via Composer:

composer require tourze/symfony-aop-lock-bundle

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

Quick Start

Annotate your methods with #[Lockable]:

use Tourze\Symfony\AopLockBundle\Attribute\Lockable;

class OrderService
{
    #[Lockable]
    public function processOrder(string $orderId): void
    {
        // business logic
    }

    #[Lockable(key: "user_{{ userId }}_update")]
    public function updateUserProfile(int $userId, array $data): void
    {
        // business logic
    }
}

The lock key can be customized using method parameters and Twig syntax, e.g. order_{{ orderId }}.
Supported Twig variables: method parameters, joinPoint.method, joinPoint.class, etc.

Documentation

API Reference
Configuration:
- Default lock timeout: 30 seconds
- All lock/unlock logic is handled automatically by the aspect
Advanced:
- Implement your own lock service by extending the aspect or LockService interface
- Customize lock behavior by overriding LockAspect

Performance & Best Practices

Only use locking where necessary, as it introduces network overhead
Keep lock scope as small as possible
Use fine-grained keys to maximize concurrency
Ensure all nodes have synchronized clocks in distributed setups
Monitor for lock timeouts and failures

Contributing

Please see CONTRIBUTING.md for details.

Issues and PRs are welcome!

Follow PSR coding standards
Add tests for new features
Run static analysis: composer phpstan

License

The MIT License (MIT). Please see License File for more information.

Changelog

See Releases for version history.

tourze / symfony-aop-lock-bundle

Maintainers

Details