README

A Laravel package for generating sequential running numbers managed by database storage. Perfect for invoice numbers, document IDs, order numbers, and any sequential identifier with custom formatting.

Requirements

• PHP 8.3+
• Laravel 11.x, 12.x, 13.x

Installation

composer require myopensoft/runner

php artisan migrate

The package auto-discovers the service provider, so no manual registration is needed.

Publish Config (optional)

php artisan vendor:publish --tag=runner-config

Publish Migrations (optional)

php artisan vendor:publish --tag=runner-migrations

Usage

Using the Static API

use MyOpensoft\Runner\Runner;

// First call creates a new sequence starting at 1
// Subsequent calls with the same rules increment the counter
$number = Runner::generate("{rule_1}-{p_raw,6}", "INV");
// Result: INV-000001, INV-000002, INV-000003, ...

Using the Facade

use MyOpensoft\Runner\Facades\Runner;

$number = Runner::generate("{rule_1}-{p_raw,6}", "INV");

Using the Helper Function

$number = runner()->next("{rule_1}-{p_raw,6}", "INV");

Using the Instance API

use MyOpensoft\Runner\Runner;

$runner = new Runner();

// Generate next number
$number = $runner->next("{rule_1}-{p_raw,6}", "INV");

// Peek at current counter without incrementing
$current = $runner->current("INV"); // returns int or null

// Reset a sequence
$runner->reset("INV");           // resets to 0
$runner->reset("INV", to: 100); // resets to 100

Format Placeholders

Unused placeholders are automatically cleaned from the output. This can be disabled via the clean_unused_placeholders config option.

Method Signatures

// Static backward-compatible API
Runner::generate(
    string $format,
    ?string $rule_1 = null,
    ?string $rule_2 = null,
    ?string $rule_3 = null,
    ?string $rule_4 = null,
    ?string $rule_5 = null,
    ?string $n_rule_1 = null,
    ?string $n_rule_2 = null,
): string

// Instance API
$runner->next(/* same signature as generate */): string
$runner->current(?string $rule_1, ..., ?string $rule_5): ?int
$runner->reset(?string $rule_1, ..., ?string $rule_5, int $to = 0): bool

Examples

// TTFN-WPPJ-(P)-000001-2020
Runner::generate(
    "{rule_1}-{rule_2}-{n_rule_1}-{p_raw,6}-{rule_3}",
    "TTFN", "WPPJ", "2020", null, null, "(P)"
);

// T20022200001
Runner::generate(
    "{rule_1}{rule_2}{rule_3}{rule_4}{p_raw,5}",
    "T", "20", "02", "22"
);

How It Works

• Each unique combination of rule_1 through rule_5 maintains its own independent counter.
• The counter automatically increments on each call with the same rule combination.
• Uses pessimistic locking (lockForUpdate()) within a database transaction to prevent race conditions.
• Rule values must not exceed 100 characters.
• Format string cannot be empty.

Configuration

// config/runner.php
return [
    'model' => \MyOpensoft\Runner\RunnerModel::class,
    'clean_unused_placeholders' => true,
];

Testing

composer test

Static analysis:

composer phpstan

License

MIT