README

A Laravel package for automatically generating unique sequential numbers for your Eloquent models.

Requirements

PHP 8.2 or higher
Laravel 10.0, 11.0, 12.0, or 13.0

Installation

Install the package via Composer:

composer require jobsrey/laravel-autonumber

Service Provider Registration

The package uses Laravel's auto-discovery feature, so the Service Provider will be automatically registered in Laravel 5.5 and above.

For older Laravel versions or if you need manual registration, add the service provider to config/app.php:

'providers' => [
    // Other Service Providers...
    Jobsrey\AutoNumber\AutoNumberServiceProvider::class,
],

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Jobsrey\AutoNumber\AutoNumberServiceProvider" --tag="config"

This will create a config/autonumber.php file with the following options:

return [
    /*
     * Autonumber format
     * '?' will be replaced with the increment number.
     */
    'format' => '?',

    /*
     * The number of digits in the autonumber
     */
    'length' => 4,

    /*
     * Whether to update the autonumber value when a model is being updated.
     * Defaults to false, which means autonumber are not updated.
     */
    'onUpdate' => false,
];

Migration

Run the migration to create the auto_numbers table:

php artisan vendor:publish --provider="Jobsrey\AutoNumber\AutoNumberServiceProvider" --tag="migrations"
php artisan migrate

Usage

Basic Usage

Add the AutoNumberTrait to your model and implement the getAutoNumberOptions() method:

use Illuminate\Database\Eloquent\Model;
use Jobsrey\AutoNumber\AutoNumberTrait;

class Invoice extends Model
{
    use AutoNumberTrait;

    protected $fillable = ['number', 'customer_id', 'amount'];

    public function getAutoNumberOptions(): array
    {
        return [
            'number' => [
                'format' => 'INV-?',  // Format: INV-0001, INV-0002, etc.
                'length' => 4,         // 4 digits with zero padding
            ],
        ];
    }
}

Now when you create a new Invoice, the number will be automatically generated:

$invoice = Invoice::create([
    'customer_id' => 1,
    'amount' => 100.00,
]);

// The number will be automatically set to: INV-0001
echo $invoice->number; // INV-0001

Multiple AutoNumber Fields

You can define multiple autonumber fields for a single model:

class Order extends Model
{
    use AutoNumberTrait;

    public function getAutoNumberOptions(): array
    {
        return [
            'order_number' => [
                'format' => 'ORD-?',
                'length' => 6,
            ],
            'reference' => [
                'format' => 'REF-?',
                'length' => 8,
            ],
        ];
    }
}

Custom Format with Callable

You can use a callable for dynamic format generation:

class Ticket extends Model
{
    use AutoNumberTrait;

    public function getAutoNumberOptions(): array
    {
        return [
            'ticket_number' => [
                'format' => function () {
                    $prefix = 'TICKET-' . date('Y');
                    return $prefix . '-?';
                },
                'length' => 5,
            ],
        ];
    }
}

Per-Model Configuration Override

You can override the global configuration for specific models:

class Product extends Model
{
    use AutoNumberTrait;

    public function getAutoNumberOptions(): array
    {
        return [
            'sku' => [
                'format' => 'SKU-?',
                'length' => 8,  // Override global length
            ],
        ];
    }
}

Update on Model Update

By default, autonumbers are only generated when creating new models. To enable autonumber generation on updates:

Set onUpdate => true in the global config (config/autonumber.php)
Or set it per-model:

class Document extends Model
{
    use AutoNumberTrait;

    public function getAutoNumberOptions(): array
    {
        return [
            'doc_number' => [
                'format' => 'DOC-?',
                'length' => 4,
                'onUpdate' => true,  // Enable update
            ],
        ];
    }
}

Configuration Options

format

The pattern for the autonumber. The ? placeholder will be replaced with the increment number.

Type: string or callable
Default: '?'
Example: 'INV-?' will generate INV-0001, INV-0002, etc.

length

The number of digits for zero-padding the increment number.

Type: int
Default: 4
Example: 4 will generate 0001, 0002, etc.

onUpdate

Whether to regenerate the autonumber when the model is updated.

Type: bool
Default: false
Note: When false, autonumbers are only generated on model creation

License

This package is open-sourced software licensed under the MIT license.

Support

For issues, questions, or contributions, please visit the GitHub repository.

jobsrey / laravel-autonumber

Maintainers

Package info

Statistics

Security