sbooker/persistent-sequences

Persistent sequences

0.5.1 2025-08-23 10:41 UTC

This package is auto-updated.

Last update: 2025-08-23 10:51:52 UTC


README

Read in English

Persistent Sequences (sbooker/persistent-sequences)

Latest Version Software License PHP Version Total Downloads

Конкурентно-безопасная, транзакционная библиотека для создания и управления именованными персистентными последовательностями.

Назначение библиотеки

Эта библиотека является идеальным инструментом для построения единых центров генерации идентификаторов (ID) и бизнес-номеров.

В сложных системах стандартного AUTO_INCREMENT бывает недостаточно. SequenceGenerator решает следующие задачи:

  • Централизованная генерация ID: В распределенных системах или при использовании подхода DDD, где ID сущности должен быть сгенерирован до ее сохранения, SequenceGenerator может выступать как надежный и транзакционный источник уникальных ID.
  • Именованные бизнес-последовательности: Создание независимых последовательностей для счетов (INV-001), заказов (ORD-002) и т.д.
  • Атомарность: Гарантированное получение следующего значения в последовательности вместе с другими операциями в рамках одной транзакции.
  • Надежность: Безопасная генерация в СУБД, где AUTO_INCREMENT имеет проблемы в кластерных конфигурациях.

Библиотека интегрирована с sbooker/transaction-manager, что гарантирует безопасность при одновременном доступе.

Ключевые особенности

  • Централизованная генерация ID: Может использоваться как единый источник правды для генерации уникальных идентификаторов сущностей.
  • Транзакционная безопасность: Генерация нового значения происходит внутри транзакции, управляемой transaction-manager.
  • Безопасность при конкурентном доступе: Использует getLocked() для предотвращения гонок данных.
  • Именованные последовательности: Неограниченное количество независимых последовательностей.
  • Гибкие алгоритмы: Используйте встроенный Increment или создайте собственную реализацию интерфейса Algorithm.
  • Разделение чтения и записи (CQRS): SequenceGenerator для изменения и SequenceReader для безопасного чтения текущего значения.

Установка

composer require sbooker/persistent-sequences

Вам также понадобится sbooker/transaction-manager и его адаптер для вашей ORM.

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

Шаг 1: Конечная цель — простое получение ID

Ваш прикладной код для генерации уникальных ID или бизнес-номеров будет выглядеть максимально просто:

// Генерируем следующий уникальный ID для нового пользователя
$nextUserId = (int)$sequenceGenerator->next('users_pk', new Algorithm\Increment(1));
$user = new User($nextUserId, /* ... */);
$transactionManager->persist($user);

// Получаем следующий номер для счета
$nextInvoiceNumber = $sequenceGenerator->next('invoices', new InvoiceAlgorithm());
// $nextInvoiceNumber будет "INV-2023-0001"

Шаг 2: Сборка зависимостей

Для работы SequenceGenerator требуется TransactionManager.

// bootstrap.php или ваш DI-контейнер

/** @var Sbooker\TransactionManager\TransactionManager $transactionManager */
$sequenceGenerator = new Sbooker\PersistentSequences\SequenceGenerator($transactionManager);

Шаг 3: Чтение текущего значения без блокировки (опционально)

Если вам нужно просто узнать последнее сгенерированное значение, не увеличивая его, используйте SequenceReader.

1. Реализуйте SequenceReadStorage:

// src/Infrastructure/Persistence/DoctrineSequenceReadStorage.php
use Doctrine\ORM\EntityManagerInterface;
use Sbooker\PersistentSequences\Sequence;
use Sbooker\PersistentSequences\SequenceReadStorage;

final class DoctrineSequenceReadStorage implements SequenceReadStorage { /* ... */ }

2. Соберите и используйте SequenceReader:

// bootstrap.php или ваш DI-контейнер
/** @var DoctrineSequenceReadStorage $readStorage */
$sequenceReader = new Sbooker\PersistentSequences\SequenceReader($readStorage);

// В вашем коде:
$lastUserId = $sequenceReader->last('users_pk');

Продвинутое использование: собственный алгоритм

Вы можете легко создать свой алгоритм, реализовав интерфейс Algorithm.

// src/Sequences/InvoiceAlgorithm.php
use Sbooker\PersistentSequences\Algorithm;

final class InvoiceAlgorithm implements Algorithm
{
    public function first(): string
    {
        return "INV-2023-0000";
    }

    public function next(string $currentValue): string
    {
        // Простая (но не идеальная) реализация для примера
        [$prefix, $year, $number] = explode('-', $currentValue);
        $nextNumber = str_pad((string)((int)$number + 1), 4, '0', STR_PAD_LEFT);

        return "$prefix-$year-$nextNumber";
    }
}

// Использование:
$nextInvoiceNumber = $sequenceGenerator->next('invoices', new InvoiceAlgorithm());
// вернет "INV-2023-0001"

License

See LICENSE file.