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

Register the bundle in your config/bundles.php if not auto-registered:

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.