Download the PHP package alimarchal/id-generator without Composer

Laravel ID Generator

A powerful Laravel package to generate unique, prefixed IDs with database transaction safety and race condition protection. Perfect for invoices, complaints, quotations, orders, and any document that needs professional numbering.

🎯 Why You Need This Package

The Problem

When building applications, you often need to generate unique document numbers like:

• Invoice Numbers: INV-20250814-0001
• Complaint IDs: CMP-20250814-0001
• Order Numbers: ORD-20250814-0001

Common challenges:

• Race Conditions: Two users creating records simultaneously can get the same number
• Non-Professional Format: Simple auto-increment IDs look unprofessional
• No Business Logic: Hard to identify document type from the number
• Maintenance Overhead: Writing custom numbering logic for each model

The Solution

This package provides:

• ✅ Race Condition Safe: Uses database transactions and row locking
• ✅ Professional Format: PREFIX-YYYYMMDD-XXXX format
• ✅ Zero Conflicts: Guaranteed unique IDs across your entire application
• ✅ Laravel Native: Follows Laravel conventions and best practices
• ✅ Future Proof: Compatible with Laravel 11, 12, and beyond
• ✅ Auto-Scalable: Handles millions of records without performance issues

🚀 Installation

That's it! Thanks to Laravel's auto-discovery, the package is immediately ready to use.

📋 Setup (One-Time)

1. Publish and Run Migration

This creates an id_prefixes table with sample data:

2. Add Your Custom Prefixes (Optional)

🎯 Usage

Method 1: Helper Functions (Recommended)

The simplest way to generate IDs anywhere in your application.

Using Database Prefixes

Using Direct Prefixes

Method 2: Dependency Injection

Perfect when you need more control or are following SOLID principles.

📊 Real-World Examples

E-Commerce Platform

Customer Support System

Complete Controller Example

🚀 Scalability & Performance

Built for Scale

• Millions of Records: Tested with millions of records without performance degradation
• High Concurrency: Can handle hundreds of simultaneous requests without conflicts
• Database Optimized: Uses efficient queries with proper indexing
• Memory Efficient: Minimal memory footprint

Race Condition Protection

🔄 Laravel Compatibility

This package is designed to work with current and future Laravel versions:

• ✅ Laravel 11 - Fully supported
• ✅ Laravel 12 - Ready for future releases
• ✅ PHP 8.2+ - Modern PHP support

Auto-Update Strategy

• Semantic Versioning: We follow SemVer for predictable updates
• Laravel Compatibility: New Laravel versions are supported within 30 days of release
• Backward Compatibility: Minor updates never break existing functionality

⚙️ Advanced Configuration

Multiple Environments

Custom Prefixes Management

🐛 Error Handling

Graceful Degradation

Common Issues & Solutions

Issue: "Prefix not found"

Issue: Column doesn't exist

📚 API Reference

Helper Functions

generateUniqueId(string $type, string $table, string $column): string

Parameters:

• $type: Type name from id_prefixes table (e.g., 'invoice')
• $table: Target database table name
• $column: Target column name for the ID

Returns: Formatted unique ID (e.g., 'INV-20250814-0001')

Throws: \Exception if type not found in database

generateUniqueIdWithPrefix(string $prefix, string $table, string $column): string

Parameters:

• $prefix: Direct prefix string (e.g., 'INV', 'CUSTOM')
• $table: Target database table name
• $column: Target column name for the ID

Returns: Formatted unique ID with custom prefix

Class Methods

IdGenerator::generate(string $type, string $table, string $column): string

Class method equivalent to generateUniqueId() helper function.

IdGenerator::generateWithPrefix(string $prefix, string $table, string $column): string

Class method equivalent to generateUniqueIdWithPrefix() helper function.

🔧 Requirements

• PHP 8.2 or higher
• Laravel 11.0 or higher
• MySQL, PostgreSQL, SQLite, or SQL Server

📖 Format Specification

ID Format: PREFIX-YYYYMMDD-XXXX

• PREFIX: 2-10 characters identifying the document type
• YYYYMMDD: Date in ISO format (e.g., 20250814 for August 14, 2025)
• XXXX: 4-digit sequential number starting from 0001 each day

Examples

🤝 Contributing

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

Development Setup

Reporting Issues

If you find a bug or have a feature request, please open an issue on GitHub.

📄 License

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

🙋 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

🔗 Related Packages

• Laravel UUID - For UUID generation
• Laravel Hashids - For URL-safe ID encoding

Made with ❤️ for the Laravel community by Ali Raza Marchal