Laravel Running Number

Generate sequential running numbers for your Laravel application. Perfect for invoice numbers, order numbers, customer IDs, and any other sequential identifiers you need.

✨ Features

• 🔢 Sequential Generation - Automatic sequential number generation per type
• 💾 Database Persistence - Reliable state storage in your database
• 🔄 Reset Periods - Automatic reset (daily, monthly, yearly, or never)
• 🔒 Thread-Safe - Race condition protection with database transactions
• 🏢 Multiple Sequences - Separate sequences per type using scopes
• 🎯 Custom Starting Numbers - Start sequences from any number
• 📊 Range Management - Set maximum limits with exception handling
• 📅 Date-Based Formats - Built-in date presenters for time-organized numbers
• 👁️ Preview Mode - Preview next numbers without incrementing
• 📦 Bulk Generation - Generate multiple numbers at once atomically
• ⚙️ Configurable - Customize padding, formatting, and behavior
• 🆔 UUID Support - Built-in UUID support for running number records
• 🏷️ Native PHP Enums - Modern PHP 8.1+ enum support with Traitify
• 🔧 Extensible - Custom generators and presenters via contracts
• 🚀 Developer Friendly - Helper functions, facades, Eloquent trait, Artisan commands, and REST API
• 🎭 Event System - Built-in events for auditing and notifications
• 🌐 REST API - Optional HTTP endpoints for remote number generation
• 📦 Wide Compatibility - Laravel 9-12 & PHP 8.1-8.4

📦 Installation

Install via Composer:

composer require cleaniquecoders/laravel-running-number

Publish and run migrations:

php artisan vendor:publish --tag="running-number-migrations"
php artisan migrate

Optionally, publish the configuration:

php artisan vendor:publish --tag="running-number-config"

📖 Detailed Guide: See the complete Installation Guide for more information.

🚀 Quick Start

Basic Usage

use CleaniqueCoders\RunningNumber\Enums\Organization;

// Using the helper function
$number = running_number()
    ->type(Organization::PROFILE->value)
    ->generate();
// Output: PROFILE001

In Model Events

use Illuminate\Database\Eloquent\Model;

class Invoice extends Model
{
    protected static function booted()
    {
        static::creating(function ($invoice) {
            $invoice->invoice_number = running_number()
                ->type('invoice')
                ->generate();
        });
    }
}

// Now every invoice automatically gets a sequential number
$invoice = Invoice::create([
    'customer_id' => 1,
    'amount' => 100.00,
]);
// invoice_number: INVOICE001

Custom Formatting

use CleaniqueCoders\RunningNumber\Contracts\Presenter;

class CustomPresenter implements Presenter
{
    public function format(string $type, int $number): string
    {
        return sprintf('%s-%04d', $type, $number);
    }
}

$number = running_number()
    ->type('invoice')
    ->formatter(new CustomPresenter())
    ->generate();
// Output: INVOICE-0001

📖 Learn More: Check out the Quick Start Guide and Common Scenarios for more examples.

📚 Documentation

Comprehensive documentation is available in the docs directory:

• Getting Started - Installation, quick start, and core concepts
• Configuration - Configuration options, types, enums, and models
• Usage - Helper functions, facades, model integration, and examples
• Advanced Features - Date formats, scopes, ranges, and more
• Development - Testing, contributing, and development setup

Quick Links

• Installation Guide
• Quick Start
• Common Scenarios
• Date-Based Formats
• Multiple Sequences
• Custom Starting Numbers
• Number Range Management
• Preview & Bulk Generation
• Upgrade Guide
• API Reference

🧪 Testing

composer test

See the Testing Guide for more information.

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🔒 Security

Please review our security policy on how to report security vulnerabilities.

🙏 Credits

• Nasrul Hazim Bin Mohamad
• All Contributors

📄 License

The MIT License (MIT). Please see License File for more information.