Download the PHP package mawuva/laravel-serial-sequence without Composer

Laravel Serial Sequence

A flexible, transactional, and extensible serial number generator for Laravel.

Laravel Serial Sequence provides a robust solution for generating unique serial numbers with automatic incrementation based on series, year, and month periods. Perfect for invoices, orders, tickets, and any business documents requiring sequential numbering with period-based resets.

Features

• Automatic serial generation with transaction safety
• Period-based sequences (year/month combinations)
• Multiple series support for different document types
• Powerful query scopes for filtering and searching
• Database-level uniqueness guarantees
• Optimized indexes for performance
• Flexible configuration options

Installation

You can install the package via composer:

You can publish and run the migrations with:

You can publish the config file with:

You can publish both migrations and config with:

Database Setup

1️. Option "Snippet / Migration Example"

Copy-paste this ready-to-use migration snippet into your migration file:

Advantages:

• No magic, fully transparent
• Easy for users who just want to copy-paste
• Complete control over column names and indexes

2️. Option "Trait Auto Add Columns" (Recommended)

Use the built-in HasSerialColumns trait for cleaner migrations:

Advantages:

• ✅ Centralized definition in the package
• ✅ Easy updates and maintenance
• ✅ Consistent across all your models
• ✅ Optional index prefix for better organization

The addSerialColumns method automatically creates:

• serie (varchar(10)) - Series identifier
• serial_year (smallint) - Year component
• serial_month (smallint) - Month component
• serial_number (unsigned int) - Sequential number
• serial (varchar, unique) - Full serial string
• Optimized indexes for performance

Usage

Basic Model Setup

Add the HasSerialSequence trait and implement the HasSerial contract:

Required Methods

When implementing the HasSerial contract, you must define:

serialSerie(): string

• Returns the series identifier for this model type
• Maximum 10 characters
• Examples: 'ORD' for orders, 'INV' for invoices, 'TICKET' for tickets

setSerialAttributes(SerialData $data): void

• Automatically handled by the HasSerialSequence trait
• Populates the model's serial fields after generation
• No manual implementation needed when using the trait

Multiple Model Examples

Creating Records with Serial Numbers

Query Scopes

The package provides powerful query scopes for filtering:

Advanced Examples

How It Works

Serial Number Format

The package generates serial numbers in the format: {SERIE}-{YEAR}-{MONTH}-{NUMBER}

Example: ORD-2024-02-0001

• SERIE: Series identifier (e.g., 'ORD' for orders, 'INV' for invoices)
• YEAR: 4-digit year (2024)
• MONTH: 2-digit month (02)
• NUMBER: Zero-padded sequential number (0001)

Automatic Reset

Serial numbers automatically reset to 1 when:

• The series changes
• The year changes
• The month changes

This ensures clean separation between different periods and document types.

Database Structure

The package uses two main tables:

1. serial_sequences - Tracks the last number used for each series/period combination
2. Your model tables - Store the actual serial data

Transaction Safety

All serial number generation happens within database transactions to prevent:

• Duplicate serial numbers
• Gaps in sequences
• Race conditions in concurrent requests

Configuration

Publishing the Config File

Publish the configuration file to customize the serial number format:

This will create config/serial-sequence.php with the default settings.

Configuration Options

Understanding the Format

With the default configuration, serial numbers are generated as:

Example with defaults:

• Serie: 'ORD'
• Year: '24' (2 digits from 2024)
• Month: '02'
• Number: '000123' (6 digits, zero-padded)
• Result: ORD-24-02-000123

Custom Format Examples

Compact Format

Result: ORD2024020001

Slash-Separated Format

Result: ORD/2024/02/00001

With Prefix

Result: COMPANY|ORD-24-02-000123

Advanced Configuration

Dynamic Prefix Resolver

You can set a custom prefix resolver that receives the model instance:

Environment-Based Configuration

Different formats for different environments:

Testing

FAQ

Q: Can I use custom serial formats?

A: Yes! Configure the serial_format in the config file to match your needs.

Q: How do I handle multiple document types?

A: Use different series identifiers for each document type (e.g., 'ORD', 'INV', 'TICKET').

Q: Are serial numbers guaranteed to be unique?

A: Yes, the package uses database constraints and transactions to ensure uniqueness.

Q: Can I manually set serial numbers?

A: While possible, it's recommended to let the package handle generation automatically.

Q: What happens if I delete records?

A: Serial numbers are not reused. The sequence continues from the last used number.

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

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

Credits

• Ephraim Seddor
• All Contributors

License

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