{"id":36386459,"url":"https://github.com/alimarchal/id-generator","last_synced_at":"2026-01-11T15:02:45.103Z","repository":{"id":309887568,"uuid":"1037897577","full_name":"alimarchal/id-generator","owner":"alimarchal","description":"Generate unique, prefixed IDs for Laravel applications with race condition protection.","archived":false,"fork":false,"pushed_at":"2025-08-14T10:42:40.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T01:37:47.929Z","etag":null,"topics":["composer-package","database-transactions","id-generator","invoice-numbering","laravel","pest-testing","php","race-condition-safe"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/alimarchal/id-generator","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alimarchal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-14T09:41:30.000Z","updated_at":"2025-08-14T10:42:44.000Z","dependencies_parsed_at":"2025-08-14T11:35:01.786Z","dependency_job_id":"95c060d5-4264-4814-b3d8-aa3cae79ade7","html_url":"https://github.com/alimarchal/id-generator","commit_stats":null,"previous_names":["alimarchal/id-generator"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/alimarchal/id-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alimarchal%2Fid-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alimarchal%2Fid-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alimarchal%2Fid-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alimarchal%2Fid-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alimarchal","download_url":"https://codeload.github.com/alimarchal/id-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alimarchal%2Fid-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28309620,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T14:58:17.114Z","status":"ssl_error","status_checked_at":"2026-01-11T14:55:53.580Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composer-package","database-transactions","id-generator","invoice-numbering","laravel","pest-testing","php","race-condition-safe"],"created_at":"2026-01-11T15:02:44.988Z","updated_at":"2026-01-11T15:02:45.093Z","avatar_url":"https://github.com/alimarchal.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laravel ID Generator\n\nA 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.\n\n```php\n// Generate professional IDs instantly\n$invoiceId = generateUniqueId('invoice', 'invoices', 'invoice_no');\n// Output: INV-20250814-0001\n\n$complaintId = generateUniqueId('complaint', 'complaints', 'complaint_no');\n// Output: CMP-20250814-0001\n```\n\n## 🎯 Why You Need This Package\n\n### The Problem\nWhen building applications, you often need to generate unique document numbers like:\n- Invoice Numbers: `INV-20250814-0001`\n- Complaint IDs: `CMP-20250814-0001` \n- Order Numbers: `ORD-20250814-0001`\n\n**Common challenges:**\n- **Race Conditions**: Two users creating records simultaneously can get the same number\n- **Non-Professional Format**: Simple auto-increment IDs look unprofessional\n- **No Business Logic**: Hard to identify document type from the number\n- **Maintenance Overhead**: Writing custom numbering logic for each model\n\n### The Solution\nThis package provides:\n- ✅ **Race Condition Safe**: Uses database transactions and row locking\n- ✅ **Professional Format**: `PREFIX-YYYYMMDD-XXXX` format\n- ✅ **Zero Conflicts**: Guaranteed unique IDs across your entire application\n- ✅ **Laravel Native**: Follows Laravel conventions and best practices\n- ✅ **Future Proof**: Compatible with Laravel 11, 12, and beyond\n- ✅ **Auto-Scalable**: Handles millions of records without performance issues\n\n## 🚀 Installation\n\n```bash\ncomposer require alimarchal/id-generator\n```\n\n**That's it!** Thanks to Laravel's auto-discovery, the package is immediately ready to use.\n\n## 📋 Setup (One-Time)\n\n### 1. Publish and Run Migration\n\n```bash\nphp artisan vendor:publish --tag=id-generator-migrations\nphp artisan migrate\n```\n\nThis creates an `id_prefixes` table with sample data:\n\n| id | name      | prefix | created_at | updated_at |\n|----|-----------|--------|------------|------------|\n| 1  | invoice   | INV    | ...        | ...        |\n| 2  | complaint | CMP    | ...        | ...        |\n| 3  | quotation | QTN    | ...        | ...        |\n\n### 2. Add Your Custom Prefixes (Optional)\n\n```php\nuse Illuminate\\Support\\Facades\\DB;\n\nDB::table('id_prefixes')-\u003einsert([\n    ['name' =\u003e 'order', 'prefix' =\u003e 'ORD'],\n    ['name' =\u003e 'receipt', 'prefix' =\u003e 'RCP'],\n    ['name' =\u003e 'estimate', 'prefix' =\u003e 'EST'],\n]);\n```\n\n## 🎯 Usage\n\n### Method 1: Helper Functions (Recommended)\n\nThe simplest way to generate IDs anywhere in your application.\n\n#### Using Database Prefixes\n\n```php\n// Generate invoice number using 'invoice' type from database\n$invoiceId = generateUniqueId('invoice', 'invoices', 'invoice_no');\n// Output: INV-20250814-0001\n\n// Generate complaint number\n$complaintId = generateUniqueId('complaint', 'complaints', 'complaint_no');\n// Output: CMP-20250814-0001\n\n// Generate quotation number\n$quotationId = generateUniqueId('quotation', 'quotations', 'quotation_no');\n// Output: QTN-20250814-0001\n```\n\n#### Using Direct Prefixes\n\n```php\n// Generate ID with custom prefix (no database lookup)\n$orderId = generateUniqueIdWithPrefix('ORD', 'orders', 'order_no');\n// Output: ORD-20250814-0001\n\n$customId = generateUniqueIdWithPrefix('CUST', 'customers', 'customer_id');\n// Output: CUST-20250814-0001\n```\n\n### Method 2: Dependency Injection\n\nPerfect when you need more control or are following SOLID principles.\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse Alimarchal\\IdGenerator\\IdGenerator;\nuse App\\Models\\Invoice;\nuse Illuminate\\Http\\Request;\n\nclass InvoiceController extends Controller\n{\n    public function store(Request $request, IdGenerator $idGenerator)\n    {\n        // Method 1: Using database prefix\n        $invoiceNumber = $idGenerator-\u003egenerate('invoice', 'invoices', 'invoice_no');\n        \n        // Method 2: Using direct prefix\n        $orderNumber = $idGenerator-\u003egenerateWithPrefix('ORD', 'orders', 'order_no');\n\n        $invoice = Invoice::create([\n            'invoice_no' =\u003e $invoiceNumber,\n            'customer_name' =\u003e $request-\u003ecustomer_name,\n            'amount' =\u003e $request-\u003eamount,\n        ]);\n\n        return response()-\u003ejson(['invoice' =\u003e $invoice], 201);\n    }\n}\n```\n\n## 📊 Real-World Examples\n\n### E-Commerce Platform\n\n```php\nclass OrderController extends Controller\n{\n    public function createOrder(Request $request, IdGenerator $idGenerator)\n    {\n        $orderNumber = $idGenerator-\u003egenerate('order', 'orders', 'order_no');\n        // Output: ORD-20250814-0001\n        \n        $invoiceNumber = $idGenerator-\u003egenerate('invoice', 'invoices', 'invoice_no');\n        // Output: INV-20250814-0001\n        \n        $trackingNumber = $idGenerator-\u003egenerateWithPrefix('TRK', 'shipments', 'tracking_no');\n        // Output: TRK-20250814-0001\n        \n        // Create order with all numbers...\n    }\n}\n```\n\n### Customer Support System\n\n```php\nclass TicketController extends Controller\n{\n    public function createTicket(Request $request)\n    {\n        $ticketNumber = generateUniqueId('ticket', 'tickets', 'ticket_no');\n        // Output: TKT-20250814-0001\n        \n        $ticket = Ticket::create([\n            'ticket_no' =\u003e $ticketNumber,\n            'title' =\u003e $request-\u003etitle,\n            'priority' =\u003e $request-\u003epriority,\n        ]);\n        \n        return response()-\u003ejson(['ticket' =\u003e $ticket], 201);\n    }\n}\n```\n\n### Complete Controller Example\n\n```php\n\u003c?php\n\nnamespace App\\Http\\Controllers;\n\nuse App\\Models\\Invoice;\nuse Illuminate\\Http\\Request;\n\nclass InvoiceController extends Controller\n{\n    public function store(Request $request)\n    {\n        // Validate request...\n        $request-\u003evalidate([\n            'customer_name' =\u003e 'required|string',\n            'amount' =\u003e 'required|numeric',\n        ]);\n\n        // Generate unique invoice number\n        $invoiceNumber = generateUniqueId('invoice', 'invoices', 'invoice_no');\n\n        // Create invoice\n        $invoice = Invoice::create([\n            'invoice_no' =\u003e $invoiceNumber,\n            'customer_name' =\u003e $request-\u003ecustomer_name,\n            'amount' =\u003e $request-\u003eamount,\n            'created_at' =\u003e now(),\n        ]);\n\n        return response()-\u003ejson([\n            'message' =\u003e 'Invoice created successfully!',\n            'invoice' =\u003e $invoice\n        ], 201);\n    }\n}\n```\n\n## 🚀 Scalability \u0026 Performance\n\n### Built for Scale\n- **Millions of Records**: Tested with millions of records without performance degradation\n- **High Concurrency**: Can handle hundreds of simultaneous requests without conflicts\n- **Database Optimized**: Uses efficient queries with proper indexing\n- **Memory Efficient**: Minimal memory footprint\n\n### Race Condition Protection\n\n```php\n// This package handles this scenario automatically:\n// User A and User B create invoices at the EXACT same millisecond\n\n// Without protection:\n// User A gets: INV-20250814-0001\n// User B gets: INV-20250814-0001 ❌ (DUPLICATE!)\n\n// With this package:\n// User A gets: INV-20250814-0001 ✅\n// User B gets: INV-20250814-0002 ✅ (UNIQUE!)\n```\n\n## 🔄 Laravel Compatibility\n\nThis package is designed to work with current and future Laravel versions:\n\n- ✅ **Laravel 11** - Fully supported\n- ✅ **Laravel 12** - Ready for future releases\n- ✅ **PHP 8.2+** - Modern PHP support\n\n### Auto-Update Strategy\n- **Semantic Versioning**: We follow [SemVer](https://semver.org/) for predictable updates\n- **Laravel Compatibility**: New Laravel versions are supported within 30 days of release\n- **Backward Compatibility**: Minor updates never break existing functionality\n\n## ⚙️ Advanced Configuration\n\n### Multiple Environments\n\n```php\n// Different prefixes for different environments\n// In your AppServiceProvider boot method:\n\nif (app()-\u003eenvironment('production')) {\n    DB::table('id_prefixes')-\u003eupdateOrInsert(\n        ['name' =\u003e 'invoice'],\n        ['prefix' =\u003e 'INV']\n    );\n} else {\n    DB::table('id_prefixes')-\u003eupdateOrInsert(\n        ['name' =\u003e 'invoice'],\n        ['prefix' =\u003e 'TEST-INV']\n    );\n}\n```\n\n### Custom Prefixes Management\n\n```php\n// Add new prefix types dynamically\nDB::table('id_prefixes')-\u003einsert([\n    'name' =\u003e 'purchase-order',\n    'prefix' =\u003e 'PO',\n    'created_at' =\u003e now(),\n    'updated_at' =\u003e now()\n]);\n\n// Use the new prefix\n$poNumber = generateUniqueId('purchase-order', 'purchase_orders', 'po_number');\n// Output: PO-20250814-0001\n```\n\n## 🐛 Error Handling\n\n### Graceful Degradation\n\n```php\n// The package includes built-in error handling\ntry {\n    $invoiceId = generateUniqueId('invoice', 'invoices', 'invoice_no');\n} catch (\\Exception $e) {\n    // If normal generation fails, package provides fallback\n    // Fallback format: INVOICE-1692012345-1234 (timestamp-based)\n    Log::error(\"ID generation failed: \" . $e-\u003egetMessage());\n    // You still get a unique ID, just less pretty\n}\n```\n\n### Common Issues \u0026 Solutions\n\n#### Issue: \"Prefix not found\"\n```php\n// Solution: Add the prefix to your database\nDB::table('id_prefixes')-\u003einsert([\n    'name' =\u003e 'your-type',\n    'prefix' =\u003e 'YOUR-PREFIX'\n]);\n```\n\n#### Issue: Column doesn't exist\n```php\n// Solution: Ensure your table has the target column\nSchema::table('your_table', function (Blueprint $table) {\n    $table-\u003estring('your_id_column')-\u003eunique();\n});\n```\n\n## 📚 API Reference\n\n### Helper Functions\n\n#### `generateUniqueId(string $type, string $table, string $column): string`\n\n**Parameters:**\n- `$type`: Type name from `id_prefixes` table (e.g., 'invoice')\n- `$table`: Target database table name\n- `$column`: Target column name for the ID\n\n**Returns:** Formatted unique ID (e.g., 'INV-20250814-0001')\n\n**Throws:** `\\Exception` if type not found in database\n\n#### `generateUniqueIdWithPrefix(string $prefix, string $table, string $column): string`\n\n**Parameters:**\n- `$prefix`: Direct prefix string (e.g., 'INV', 'CUSTOM')\n- `$table`: Target database table name  \n- `$column`: Target column name for the ID\n\n**Returns:** Formatted unique ID with custom prefix\n\n### Class Methods\n\n#### `IdGenerator::generate(string $type, string $table, string $column): string`\n\nClass method equivalent to `generateUniqueId()` helper function.\n\n#### `IdGenerator::generateWithPrefix(string $prefix, string $table, string $column): string`\n\nClass method equivalent to `generateUniqueIdWithPrefix()` helper function.\n\n## 🔧 Requirements\n\n- PHP 8.2 or higher\n- Laravel 11.0 or higher\n- MySQL, PostgreSQL, SQLite, or SQL Server\n\n## 📖 Format Specification\n\n### ID Format: `PREFIX-YYYYMMDD-XXXX`\n\n- **PREFIX**: 2-10 characters identifying the document type\n- **YYYYMMDD**: Date in ISO format (e.g., 20250814 for August 14, 2025)\n- **XXXX**: 4-digit sequential number starting from 0001 each day\n\n### Examples\n\n| Document Type | Generated ID | Description |\n|---------------|--------------|-------------|\n| Invoice | `INV-20250814-0001` | First invoice of August 14, 2025 |\n| Complaint | `CMP-20250814-0001` | First complaint of August 14, 2025 |\n| Order | `ORD-20250814-0053` | 53rd order of August 14, 2025 |\n| Custom | `CUSTOM-20250814-0001` | Custom prefix example |\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/alimarchal/id-generator.git\ncd id-generator\ncomposer install\n```\n\n### Reporting Issues\n\nIf you find a bug or have a feature request, please [open an issue](https://github.com/alimarchal/id-generator/issues) on GitHub.\n\n## 📄 License\n\nThis package is open-sourced software licensed under the [MIT license](LICENSE).\n\n## 🙋 Support\n\n- **Issues**: [GitHub Issues](https://github.com/alimarchal/id-generator/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/alimarchal/id-generator/discussions)\n- **Email**: kh.marchal@gmail.com\n\n## 🔗 Related Packages\n\n- [Laravel UUID](https://github.com/webpatser/laravel-uuid) - For UUID generation\n- [Laravel Hashids](https://github.com/vinkla/laravel-hashids) - For URL-safe ID encoding\n\n---\n\n**Made with ❤️ for the Laravel community by [Ali Raza Marchal](https://github.com/alimarchal)**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falimarchal%2Fid-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falimarchal%2Fid-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falimarchal%2Fid-generator/lists"}