README

VsE/codegenerator - Dynamic Unique Code Generator for Laravel A robust, flexible, and pattern-based package to generate unique identifiers (codes) for various entities within your Laravel application (e.g., order numbers, invoice IDs, tracking codes). It features thread-safe sequence management, configurable patterns, and supports different types of unique components (sequential, random, UUIDs).

Installation Add to your project: If developing locally within your packages directory: Add the following to your main composer.json file in the autoload section:

"autoload": { "psr-4": { "App\": "app/", "vsent\\Codegenerator\": "packages/vse/codegenerator/src/" // Add this line } }, "repositories": [ { "type": "path", "url": "./packages/vse/codegenerator" } ]

Then run composer dump-autoload.

If installing via Packagist (after publishing your package):

composer require vse/codegenerator

Publish Configuration & Migrations: After installation, publish the package's configuration file and database migrations:

php artisan vendor:publish --tag=codegenerator-config php artisan vendor:publish --tag=codegenerator-migrations

This will create config/codegenerator.php and a migration file in database/migrations.

Run Migrations: Execute the migrations to create the code_sequences table:

php artisan migrate

Configuration (config/codegenerator.php) The config/codegenerator.php file (published in step 2) is where you define global settings and specific patterns for your codes. Refer to the extensive comments within that file for detailed explanations of each option and placeholder.

Usage You can use the CodeGenerator Facade to generate codes.

1. Generating a Predefined Code Type This is the most common and recommended way to generate codes, using patterns defined in your config/codegenerator.php.

use vsent\Codegenerator\Facades\CodeGenerator;

// Generate an Order Code (uses 'order' pattern from config) try { $orderCode = CodeGenerator::generateFor('order'); // Example: ORD-250609-HQ-0001 } catch (\RuntimeException $e) { // Handle error (e.g., max attempts reached, database error) echo "Error generating order code: " . $e->getMessage(); }

// Generate an Invoice Number (uses 'invoice' pattern from config) try { $invoiceNumber = CodeGenerator::generateFor('invoice'); // Example: INV-202506-MUM-00001 } catch (\RuntimeException $e) { echo "Error generating invoice: " . $e->getMessage(); }

// Generate a Tracking ID (uses 'tracking_id' pattern, which generates UUIDs) try { $trackingId = CodeGenerator::generateFor('tracking_id'); // Example: TRK-a1b2c3d4-e5f6-7890-1234-567890abcdef } catch (\RuntimeException $e) { echo "Error generating tracking ID: " . $e->getMessage(); }

1. Generating with Runtime Overrides You can temporarily override specific configuration settings for a single generation call.

use vsent\Codegenerator\Facades\CodeGenerator;

// Generate a Purchase Order code, but specify a different location for this instance try { $poCodeForLondon = CodeGenerator::generateFor('purchase_order', [ 'location' => 'LDN', // Override the default 'NYC' for this generation 'sequence_length' => 6 // Override default 5-digit sequence ]); // Example: PO/LDN/20250609/000001 } catch (\RuntimeException $e) { echo "Error generating PO code: " . $e->getMessage(); }

1. Generating with an Inline (Ad-Hoc) Pattern For one-off or dynamic code structures not defined in the config, you can pass the pattern directly.

use vsent\Codegenerator\Facades\CodeGenerator;

// Generate a custom short code for an event registration try { $eventCode = CodeGenerator::generateFor('EVT-{DATE:md}-{RANDOM:4}', [ 'type' => 'EVENT', // Type used for placeholder and sequence tracking if applicable 'code_length' => 12 // Ensure total length is 12 ]); // Example: EVT-0609-ABCD0000 } catch (\RuntimeException $e) { echo "Error generating event code: " . $e->getMessage(); }

1. Confirming Usage for Sequential Codes (Crucial!) For any code generated using the {SEQUENCE} placeholder, it's CRUCIAL to call confirmUsage() once the code has been successfully processed and committed in your application (e.g., after saving an order to the database). This updates the sequence in the code_sequences table, ensuring proper sequential numbering and preventing gaps in your confirmed sequences if a generated code isn't actually used.

use vsent\Codegenerator\Facades\CodeGenerator; use Illuminate\Support\Facades\DB; // Example of wrapping in a transaction

try { DB::beginTransaction();

$orderCode = CodeGenerator::generateFor('order');
// ... logic to save the order to your 'orders' table using $orderCode ...

if (CodeGenerator::confirmUsage($orderCode)) {
    DB::commit();
    echo "Order created and code confirmed: " . $orderCode;
} else {
    DB::rollBack();
    echo "Failed to confirm order code usage. Transaction rolled back.";
}

} catch (\RuntimeException $e) { DB::rollBack(); echo "Error during order creation: " . $e->getMessage(); }

// Note: For codes generated with {UUID} or {RANDOM}, confirmUsage() is generally not needed, // as their uniqueness is inherent and not managed by a shared sequence counter.

Contributing Feel free to open issues or pull requests on the GitHub repository.

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