README

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

🧪 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

📄 License

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

cleaniquecoders / laravel-running-number

Maintainers

Details