Download the PHP package kabiroman/ttlsemlock-client without Composer

TtlSemLock PHP Client

🔒 High-performance PHP client for TtlSemLock distributed semaphore

Features

• 🚀 High Performance: Sub-millisecond operation latency
• 🔐 Full API Coverage: acquire, release, exists, stats, extend
• ⏰ TTL Support: Automatic lock expiration with extend capability
• 🔄 Retry Logic: Built-in retry mechanisms for lock contention
• 🛡️ Error Handling: Comprehensive exception hierarchy
• 📦 PSR-4 Compatible: Modern PHP package structure
• 🧪 Well Tested: Comprehensive examples and tests
• 🔗 Symfony Integration: Compatible with Symfony Lock Component
• 📋 Broad Compatibility: PHP 8.1+ and Symfony 6.4+ support
• 🔐 Enterprise Security: API Key authentication (v0.4.0+)

Requirements

• PHP: 8.1+
• Extensions: json, sockets (for TCP connections)
• Symfony Lock (optional): 6.4+ or 7.0+

📋 See COMPATIBILITY.md for detailed version support and migration guide

Compatibility Matrix

Framework Support

Installation

Via Composer (Recommended)

For Symfony Integration

Manual Installation

1. Download the source code
2. Include the autoloader:

Quick Start

Basic Usage

Using with API Key (v0.4.0+)

For production environments with API key authentication enabled:

Advanced Usage

Symfony Integration

TtlSemLock can be used as a backend for Symfony Lock Component:

Symfony Framework Configuration

For Symfony 6.4 LTS (PHP 8.1+)

For Symfony 7.0+ (PHP 8.2+)

Environment Variables

Service Configuration with API Key (v0.4.0+)

Security Configuration (v0.4.0+)

TtlSemLock supports API Key authentication for secure production deployments:

Server Configuration

Create config.security.json:

Start server with security:

PHP Client with Authentication

Error Handling

Best Practices

• 🔑 Use strong API keys: Minimum 32 characters, random generation
• 🔄 Rotate keys regularly: Update API keys every 90-180 days
• 🌍 Environment separation: Different keys for prod/staging/dev
• 📝 Monitor auth failures: Track failed authentication attempts
• 🚫 Disable auth in development: Set auth_required: false locally
• 🔒 Secure key storage: Use environment variables, not hardcoded keys

API Reference

Constructor

Core Methods

acquire(string $key, int $ttl, string $pid = '', string $host = ''): bool

Acquire a distributed lock.

• $key: Lock identifier
• $ttl: Time to live in seconds (max 86400)
• $pid: Process identifier (auto-detected if empty)
• $host: Host identifier (auto-detected if empty)
• Returns: true if acquired, false if already locked

release(string $key): bool

Release a distributed lock.

• $key: Lock identifier
• Returns: true if released, false if lock didn't exist

exists(string $key): bool

Check if a lock exists and is active.

• $key: Lock identifier
• Returns: true if lock exists and is active

extend(string $key, int $ttl, string $owner): bool

Extend TTL of an existing lock.

• $key: Lock identifier
• $ttl: New TTL in seconds (max 86400)
• $owner: Owner in format "pid@host"
• Returns: true if extended, false if failed

stats(): array

Get server statistics.

• Returns: Array with server stats (TotalRequests, ActiveLocks, etc.)

Convenience Methods

acquireWithOwner(string $key, int $ttl): ?string

Acquire lock with automatic owner generation.

• Returns: Owner string if acquired, null if failed

acquireWithRetry(string $key, int $ttl, int $maxRetries = 3, int $retryDelay = 100000): ?string

Try to acquire lock with retry logic.

• $maxRetries: Maximum retry attempts
• $retryDelay: Delay between retries in microseconds
• Returns: Owner string if acquired, null if failed

withLock(string $key, int $ttl, callable $callback, ...$args): mixed

Execute a callback with distributed lock.

• $callback: Function to execute while locked
• $args: Arguments to pass to callback
• Returns: Return value of callback
• Throws: TtlSemLockException if lock cannot be acquired

Examples

Basic Lock Operations

TTL Extension

Retry Logic

Callback Pattern

Migration Guide

From Redis/Memcached to TtlSemLock

Replace your existing Symfony Lock store configuration:

Version Compatibility Testing

Test compatibility with your PHP/Symfony versions:

Performance Comparison

Error Handling

The client throws specific exceptions for different error types:

Performance

The PHP client is optimized for high performance:

• ~0.1-0.2ms average operation latency
• 5000+ ops/sec throughput on modern hardware
• Minimal memory footprint
• Connection pooling ready

Run the performance test:

Requirements

• PHP 8.0+
• TCP connection to TtlSemLock server
• JSON extension (included in PHP by default)

Configuration

Connection Settings

Server Configuration

Ensure your TtlSemLock server is configured correctly:

Testing

Run the examples to test functionality:

Contributing

1. Fork the repository
2. Create your feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation: Main README
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

TtlSemLock PHP Client - Part of the TtlSemLock distributed semaphore system.