Laravel Sequence

A lightweight, flexible Laravel package for generating format-based sequential values with safe DB locking and reset policies.

Features

• Concurrent-safe sequence generation with DB row locking
• Custom patterns: {YYYY}, {MM}, {DD}, {H}, {M}, {S}, {SEQ}, {SEQ:N}, {FY}
• Reset policies: none, yearly, monthly, daily, financial_year
• Model-scoped sequences (per record)
• Preview next value without incrementing

Installation

Install via Composer:

composer require tenthfeet/laravel-sequence

Publish config and migration:

php artisan vendor:publish --provider="Tenthfeet\Sequence\SequenceServiceProvider" --tag="config"
php artisan vendor:publish --provider="Tenthfeet\Sequence\SequenceServiceProvider" --tag="migrations"

Run migrations:

php artisan migrate

Configuration

Published config: config/sequences.php

return [
    'table' => 'sequences',
    'default_pattern' => '{SEQ:3}',
    'default_padding_character' => '0',
    'default_reset_policy' => \Tenthfeet\Sequence\Enums\ResetPolicy::None,
    'financial_year' => [
        'start_month' => \Carbon\Month::April,
    ],
];

Define a sequence

Create a sequence definition:

php artisan make:sequence InvoiceSequence

Example class:

namespace App\Sequences;

use Tenthfeet\Sequence\SequenceDefinition;
use Tenthfeet\Sequence\Enums\ResetPolicy;

final class InvoiceSequence extends SequenceDefinition
{
    public function key(): string
    {
        return 'invoice';
    }

    public function __construct()
    {
        $this->pattern('INV-{YYYY}-{SEQ:4}')
            ->resetPolicy(ResetPolicy::Yearly);
    }
}

Generate sequences

use Tenthfeet\Sequence\Sequence;
use App\Sequences\InvoiceSequence;

$sequence = new InvoiceSequence();
$value = Sequence::using($sequence)->next();
$preview = Sequence::using($sequence)->previewNext();

Model-specific sequences

use App\Sequences\ProjectTaskSequence;
use Tenthfeet\Sequence\Sequence;

$project = App\Models\Project::find(1);
$definition = (new ProjectTaskSequence())->forModel($project);
$value = Sequence::using($definition)->next();

Runtime overrides

$definition = (new InvoiceSequence())
    ->pattern('INV-{YYYY}-{MM}-{SEQ:5}')
    ->padWith('0')
    ->usingDate(now());
$value = Sequence::using($definition)->next();

Pattern tokens

Reset policies

use Tenthfeet\Sequence\Enums\ResetPolicy;

ResetPolicy::None;
ResetPolicy::Yearly;
ResetPolicy::Monthly;
ResetPolicy::Daily;
ResetPolicy::FinancialYear;

Notes

Sequence rows are grouped by key, reset_value, and optional model_type / model_id.

License

MIT