README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Lock

Блокировки ресурсов для PHP 8.1+: межпроцессные (flock), распределённые (PSR-16 кэш) и внутрипроцессные (в памяти) из одного пакета. Токен владельца (чужую блокировку не снять), TTL с инъектируемыми часами (PSR-20) для детерминированных тестов и synchronized() с гарантированным снятием. Минимум зависимостей.

Установка

composer require cloud-castle/lock

Требуется PHP 8.1+.

Быстрый старт

<?php

use CloudCastle\Lock\Locks;

// Межпроцессная блокировка на flock: атомарна между процессами.
$lock = Locks::flock('/var/lock/app')->create('order:42');

if ($lock->acquire()) {
    try {
        // критическая секция — ресурс держим только мы
    } finally {
        $lock->release();
    }
}

// Одним вызовом: захватить → выполнить → гарантированно снять (даже при исключении).
$result = Locks::flock('/var/lock/app')
    ->create('report:daily')
    ->synchronized(static fn (): string => generateReport());

// Распределённая блокировка через любой PSR-16 кэш (Redis, Memcached, ...).
$lock = Locks::cache($psr16Cache)->create('payment:777', ttlSeconds: 30);

// Внутрипроцессная блокировка с детерминированным TTL в тестах —
// подмените системные часы на mock/frozen (PSR-20).
$lock = Locks::inMemory($mockClock)->create('job', ttlSeconds: 30);

Возможности

Три бэкенда из коробки: FlockStore (межпроцессный flock), CacheLockStore (распределённый поверх PSR-16) и InMemoryStore (внутрипроцессный) — единый API через фасад Locks.
Токен владельца: снять или продлить блокировку может только её держатель — чужой токен не освободит ресурс (защита от случайного снятия).
synchronized(): критическая секция с захватом, выполнением и гарантированным снятием в finally (в том числе при исключении).
TTL с инъектируемыми часами (PSR-20): истечение блокировки детерминировано в тестах — «перематывайте» время FrozenClock/MockClock без реального ожидания.
Переиспользование дескрипторов во FlockStore: повторный захват одного ресурса не платит за fopen/fclose — быстрый горячий путь для воркеров.
Хеширование имени ресурса (SHA-256): нет traversal и недопустимых символов в имени lock-файла или ключе кэша.
Минимум зависимостей — только PSR-контракты и cloud-castle/clock.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	symfony	malkusch	ninja-mutex	flock¹
Несколько бэкендов из коробки (память / flock / PSR-16 кэш)	✅	✅	✅	✅	❌
Инъектируемые часы (PSR-20) — детерминированный TTL в тестах	✅	❌	❌	❌	❌
Токен владельца (снять/продлить может только держатель)	✅	✅	❌	❌	❌
synchronized() — критическая секция с гарантированным снятием	✅	❌	✅	❌	❌
Минимум зависимостей (только PSR + cloud-castle/clock)	✅	❌	✅	✅	✅
Всего	🏆 5	2	3	2	1

2. Безопасность и корректность

Свойство	🏆 CloudCastle	symfony	malkusch	ninja-mutex	flock¹
Токен владельца (защита от снятия чужой блокировки)	✅	✅	❌	❌	❌
Fail-safe: истёкшая блокировка освобождается автоматически (TTL)	✅	✅	✅	❌	❌
Атомарный межпроцессный захват (flock LOCK_EX/LOCK_NB)	✅	✅	✅	✅	✅
Хеширование имени ресурса SHA-256 (нет traversal в имени файла/ключе)	✅	✅	❌	❌	❌
Детерминированное истечение TTL (инъектируемые часы для аудита)	✅	❌	❌	❌	❌
Всего	🏆 5	4	2	1	1

3. Производительность

acquire + release flock-блокировки, 50 000 раз (минимум из 4).

Решение	Время (мс)	Итог
flock¹	48,5	базовый уровень (не библиотека)
🏆 CloudCastle	65,4	быстрейшее среди библиотек
malkusch	65,9	аналог
ninja-mutex	364,4	аналог
symfony	376,4	аналог

4. Потребление памяти

Пик памяти на 50 000 операций (изолированный процесс, только целевая библиотека).

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	6 965	легчайшее среди библиотек
symfony	6 965	аналог
malkusch	6 965	аналог
ninja-mutex	6 965	аналог
flock¹	6 965	базовый уровень (не библиотека)

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

Вывод: CloudCastle Lock — самый функциональный и безопасный среди рассмотренных: единственный, кто даёт три бэкенда (память/flock/PSR-16), токен владельца, synchronized() и тестируемый TTL на инъектируемых часах одновременно, и при этом кратно быстрее высокоуровневых аналогов (symfony/lock, arvenil/ninja-mutex). В чистой flock-скорости он идёт статистически вровень с самым лёгким низкоуровневым malkusch/lock (разница — в пределах погрешности измерения), но при этом добавляет токен владельца, несколько бэкендов и PSR-20-часы, которых у того нет. Рекомендуется, когда нужны надёжные блокировки именованных ресурсов с защитой владельца и лёгкой тестируемостью; для голого межпроцессного flock без дополнительных гарантий достаточно и нативного вызова.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/lock
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия