README

PDO implementation of RandomSequenceInterface for the PimBay Sequence Stack. Supports MySQL, MariaDB, PostgreSQL, SQLite, and MSSQL.

Code uniqueness is guaranteed by a UNIQUE(group_id, code) database constraint — no application-level locking required.

Installation

composer require pimbay-php/sequence-random-pdo

Usage

Schema setup

use PimBay\Sequence\Random\Pdo\SchemaManager;

$schema = new SchemaManager($pdo);
$schema->createTable();                        // default table: pimbay_sequence_random
$schema->createTable('my_custom_table');       // custom table name

createTable() is idempotent — safe to call on every deploy.

Basic usage

use PimBay\Sequence\Random\Pdo\RandomSequence;
use PimBay\Sequence\Random\Pdo\Adapter\DriverDetectingAdapter;

$adapter = new DriverDetectingAdapter($pdo);
$sequence = new RandomSequence($pdo, $adapter, $generatorFactory);

// Create a sequence — binds a code generator to a group+name pair
$result = $sequence->createSequence('vouchers', 'christmas_2026', $generator, ['channel' => 'email']);

// Generate unique codes
$code = $sequence->nextCode('vouchers', 'christmas_2026', context: ['country' => 'SK'], metadata: ['batch' => 'q4']);

// Reserve a fixed code — prevents random generation of the same code
$sequence->insertCode('vouchers', 'christmas_2026', 'VIANOCE2026', ['source' => 'import_2026_q1']);

// Check existence — scoped to group
$exists = $sequence->exists('vouchers', 'VIANOCE2026');

// Read current sequence state
$state = $sequence->getCurrent('vouchers', 'christmas_2026');
// $state->group, $state->name, $state->metadata, $state->createdAt, $state->generatorConfig

Adapters

DriverDetectingAdapter resolves the correct adapter from the PDO driver name automatically:

use PimBay\Sequence\Random\Pdo\Adapter\DriverDetectingAdapter;

// Auto-detects: mysql → MysqlAdapter, pgsql → PostgresAdapter, sqlite → SqliteAdapter, sqlsrv → MssqlAdapter
$adapter = new DriverDetectingAdapter($pdo);

// Custom table name — must match the table used in RandomSequence
$adapter = new DriverDetectingAdapter($pdo, 'my_custom_table');

// Custom adapter map — extend with your own driver
$adapter = new DriverDetectingAdapter($pdo, 'my_table', ['oracle' => MyOracleAdapter::class]);

Concrete adapters can be used directly:

use PimBay\Sequence\Random\Pdo\Adapter\MysqlAdapter;
use PimBay\Sequence\Random\Pdo\Adapter\PostgresAdapter;
use PimBay\Sequence\Random\Pdo\Adapter\SqliteAdapter;
use PimBay\Sequence\Random\Pdo\Adapter\MssqlAdapter;

$adapter = new MysqlAdapter($pdo, $tableName);

Custom table name

Pass the same table name consistently to RandomSequence, DriverDetectingAdapter, and SchemaManager:

$tableName = 'my_voucher_sequences';

$schema = new SchemaManager($pdo);
$schema->createTable($tableName);

$adapter = new DriverDetectingAdapter($pdo, $tableName);
$sequence = new RandomSequence($pdo, $adapter, $generatorFactory, $tableName);

Exception handling

All exceptions implement SequenceExceptionInterface:

use PimBay\Sequence\Exception\SequenceExceptionInterface;
use PimBay\Sequence\Exception\SequenceNotFoundException;
use PimBay\Sequence\Exception\SequenceAlreadyExistsException;
use PimBay\Sequence\Exception\SequenceCollisionException;
use PimBay\Sequence\Exception\CodeAlreadyExistsException;

try {
    $code = $sequence->nextCode('vouchers', 'christmas_2026');
} catch (SequenceCollisionException $e) {
    // max attempts exceeded — generator alphabet too small or sequence exhausted
} catch (SequenceNotFoundException $e) {
    // sequence does not exist — createSequence() was not called
} catch (SequenceExceptionInterface $e) {
    // catch-all for any sequence exception
}

Schema SQL access

Raw SQL statements are available as public constants for migrations:

use PimBay\Sequence\Random\Pdo\SchemaManager;

// Per-driver statement arrays — each element is one CREATE TABLE statement
SchemaManager::MYSQL_CREATE_TABLE_STATEMENTS;
SchemaManager::MARIADB_CREATE_TABLE_STATEMENTS;
SchemaManager::POSTGRES_CREATE_TABLE_STATEMENTS;
SchemaManager::SQLITE_CREATE_TABLE_STATEMENTS;

// Full SQL string (statements joined with \n\n)
$pdo = new PDO('sqlite::memory:');
$sql = (new SchemaManager($pdo))->getCreateTableSql('my_table');

Test matrix

PHP	MySQL 8.0	MariaDB 11	PostgreSQL 16	SQLite
8.3	✅	✅	✅	✅
8.4	✅	✅	✅	✅
8.5	✅	✅	✅	✅

Packages in the stack

Package	Description
`pimbay/sequence-random-sql`	SQL snippets for random sequence adapters
`pimbay-php/sequence`	Interfaces, results, exceptions
`pimbay-php/sequence-formatter`	Pattern formatter, code generator, alphabet
`pimbay-php/sequence-random-pdo`	This package — PDO adapter for random sequences

License

Public domain — Unlicense

pimbay-php / sequence-random-pdo

Maintainers

Package info

Statistics

Security