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

Placeholder	Description
`{rule_1}` to `{rule_5}`	Indexed rules — stored in database and used to identify the sequence
`{n_rule_1}`, `{n_rule_2}`	Non-indexed rules — included in output only, not stored in database
`{raw}`	Raw sequential number
`{p_raw,N}`	Left-padded sequential number (e.g., `{p_raw,6}` → `000001`)

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

myopensoft / runner

Maintainers

Package info

Statistics

Security