Enhance package with UUID support, native PHP enums, and improved running number features

- Added UUID column to running_numbers table and migration for existing records
- Migrated from Spatie enums to native PHP enums with Traitify integration
- Updated running number generation to support multiple sequences and custom starting points
- Improved README and CHANGELOG with detailed feature descriptions and usage examples
- Updated tests to validate UUID generation and uniqueness

Author: nasrulhazim

.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(composer require:*)",
+      "Bash(composer update:*)",
+      "Bash(composer test:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

.github/workflows/run-tests.yml

@@ -2,21 +2,33 @@ name: run-tests
 
 on:
   push:
-    branches: [main]
-  pull_request:
-    branches: [main]
+    paths:
+      - '**.php'
+      - '.github/workflows/run-tests.yml'
+      - 'phpunit.xml.dist'
+      - 'composer.json'
+      - 'composer.lock'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   test:
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 5
     strategy:
       fail-fast: true
       matrix:
-        os: [ubuntu-latest, windows-latest]
-        php: [8.1, 8.2]
-        laravel: [10.*]
-        stability: [prefer-lowest, prefer-stable]
+        os: [ubuntu-latest]
+        php: [8.2, 8.3, 8.4]
+        laravel: [12.*, 11.*, 10.*]
+        stability: [prefer-stable]
         include:
+          - laravel: 12.*
+            testbench: 10.*
+          - laravel: 11.*
+            testbench: 9.*
           - laravel: 10.*
             testbench: 8.*
 
@@ -47,4 +59,4 @@ jobs:
         run: composer show -D
 
       - name: Execute tests
-        run: vendor/bin/pest
+        run: vendor/bin/pest --ci

CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes to `laravel-running-number` will be documented in this file.
 
+## v3.0.0 - Major Feature Release (Planned)
+
+Version 3.0.0 represents a major advancement in the package, implementing comprehensive feature enhancements and architectural improvements.
+
+### 🚀 Major Features
+
+#### Traitify Integration
+- **Native PHP Enums Support** - Migrated from `spatie/laravel-enum` to native PHP 8.1+ enums with `cleaniquecoders/traitify`
+- **UUID Support** - Full UUID support via `InteractsWithUuid` trait
+- **Enum Methods** - Enhanced enum capabilities with `values()`, `labels()`, `options()`, `descriptions()`
+
+#### Running Number Management
+- **Reset/Restart Functionality** - Reset running numbers or restart from custom starting points
+- **Date-Based Formats** - Generate numbers with configurable date components (e.g., `INV-2024-01-001`)
+- **Multiple Sequences** - Maintain separate sequences for the same type (branch-specific, department-specific)
+- **Custom Starting Numbers** - Configure custom starting numbers per type
+- **Range Management** - Define and enforce number ranges with overflow detection
+
+#### Generation Features
+- **Preview Mode** - Preview next number without persisting to database
+- **Bulk Generation** - Efficiently generate multiple numbers in a single operation
+- **Threading Safety** - Improved concurrency handling for high-volume generation
+- **Audit Trail** - Optional generation history tracking with user attribution
+
+#### Developer Experience
+- **Eloquent Trait** - New `HasRunningNumber` trait for seamless model integration
+- **Artisan Commands** - CLI commands for list, reset, restart, preview, and statistics
+- **Events System** - `RunningNumberGenerated` and `RunningNumberReset` events for extensibility
+- **Service Container Integration** - Enhanced dependency injection support
+
+### 📚 Documentation
+- Complete documentation overhaul with structured guides
+- 20+ dedicated documentation files organized in progressive learning path
+- Comprehensive examples for common scenarios
+- Advanced integration patterns guide
+- Developer contribution guidelines
+
+### ⚡ Breaking Changes
+
+**Enum Migration**: Updated from Spatie enums to native PHP enums with Traitify
+**Database Schema**: Added required `uuid` column to `running_numbers` table
+**Configuration**: Extended with new options for reset periods, date formats, starting numbers, and audit trail
+
+See the [Upgrade Guide](docs/06-upgrade-guide.md) for detailed migration instructions.
+
+### 📦 Dependencies
+- Added `cleaniquecoders/traitify` for UUID and enum support
+- Minimum PHP 8.1+ required
+- Laravel 9-12 supported
+
+**Full Documentation**: See [docs/06-upgrade-guide.md](docs/06-upgrade-guide.md) for complete v3.0.0 upgrade guide
+
+---
+
 ## Added Laravel 12 and PHP 8.4 Support - 2025-05-01
 
 ### What's Changed

README.md

@@ -1,70 +1,152 @@
-# Generate running number when creating new records in your table.
+# Laravel Running Number
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/cleaniquecoders/laravel-running-number.svg?style=flat-square)](https://packagist.org/packages/cleaniquecoders/laravel-running-number)
 [![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/cleaniquecoders/laravel-running-number/run-tests?label=tests)](https://github.com/cleaniquecoders/laravel-running-number/actions?query=workflow%3Arun-tests+branch%3Amain)
 [![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/cleaniquecoders/laravel-running-number/Check%20&%20fix%20styling?label=code%20style)](https://github.com/cleaniquecoders/laravel-running-number/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain)
 [![Total Downloads](https://img.shields.io/packagist/dt/cleaniquecoders/laravel-running-number.svg?style=flat-square)](https://packagist.org/packages/cleaniquecoders/laravel-running-number)
 
-Generate running number when creating new records in your table.
+Generate sequential running numbers for your Laravel application. Perfect for invoice numbers, order numbers, customer IDs, and any other sequential identifiers you need.
 
-## Installation
+## ✨ Features
 
-You can install the package via composer:
+- 🔢 **Sequential Generation** - Automatic sequential number generation per type
+- 💾 **Database Persistence** - Reliable state storage in your database
+- ⚙️ **Configurable** - Customize padding, formatting, and behavior
+- 🆔 **UUID Support** - Built-in UUID support for running number records
+- 🏷️ **Native PHP Enums** - Modern PHP 8.1+ enum support with Traitify
+- 🔧 **Extensible** - Custom generators and presenters via contracts
+- 🚀 **Developer Friendly** - Helper functions, facades, and excellent IDE support
+- ✅ **Well Tested** - Comprehensive test coverage
+- 📦 **Wide Compatibility** - Laravel 9-12 & PHP 8.1-8.4
+
+## 📦 Installation
+
+Install via Composer:
 
 ```bash
 composer require cleaniquecoders/laravel-running-number
 ```
 
-You can publish and run the migrations with:
+Publish and run migrations:
 
 ```bash
 php artisan vendor:publish --tag="running-number-migrations"
 php artisan migrate
 ```
 
-You can publish the config file with:
+Optionally, publish the configuration:
 
 ```bash
 php artisan vendor:publish --tag="running-number-config"
 ```
 
-Please make sure to configure the `config/running-number` types, in order to support your requirement.
+> **📖 Detailed Guide**: See the complete [Installation Guide](docs/01-getting-started/01-installation.md) for more information.
 
-## Usage
+## 🚀 Quick Start
+
+### Basic Usage
 
 ```php
-running_number()->type($type)->generate();
+use CleaniqueCoders\RunningNumber\Enums\Organization;
+
+// Using the helper function
+$number = running_number()
+    ->type(Organization::PROFILE->value)
+    ->generate();
+// Output: PROFILE001
+```
+
+### In Model Events
 
-// OR
+```php
+use Illuminate\Database\Eloquent\Model;
+
+class Invoice extends Model
+{
+    protected static function booted()
+    {
+        static::creating(function ($invoice) {
+            $invoice->invoice_number = running_number()
+                ->type('invoice')
+                ->generate();
+        });
+    }
+}
+
+// Now every invoice automatically gets a sequential number
+$invoice = Invoice::create([
+    'customer_id' => 1,
+    'amount' => 100.00,
+]);
+// invoice_number: INVOICE001
+```
 
-use CleaniqueCoders\RunningNumber\Generator as RunningNumberGenerator;
+### Custom Formatting
 
-RunningNumberGenerator::make()->type($type)->generate();
+```php
+use CleaniqueCoders\RunningNumber\Contracts\Presenter;
+
+class CustomPresenter implements Presenter
+{
+    public function format(string $type, int $number): string
+    {
+        return sprintf('%s-%04d', $type, $number);
+    }
+}
+
+$number = running_number()
+    ->type('invoice')
+    ->formatter(new CustomPresenter())
+    ->generate();
+// Output: INVOICE-0001
 ```
 
-## Testing
+> **📖 Learn More**: Check out the [Quick Start Guide](docs/01-getting-started/02-quick-start.md) and [Common Scenarios](docs/03-usage/05-common-scenarios.md) for more examples.
+
+## 📚 Documentation
+
+Comprehensive documentation is available in the [docs](docs/) directory:
+
+- **[Getting Started](docs/01-getting-started/)** - Installation, quick start, and core concepts
+- **[Configuration](docs/02-configuration/)** - Configuration options, types, enums, and models
+- **[Usage](docs/03-usage/)** - Helper functions, facades, model integration, and examples
+- **[Advanced Topics](docs/04-advanced/)** - Custom presenters, generators, and integrations
+- **[Development](docs/05-development/)** - Testing, contributing, and development setup
+
+### Quick Links
+
+- [Installation Guide](docs/01-getting-started/01-installation.md)
+- [Quick Start](docs/01-getting-started/02-quick-start.md)
+- [Common Scenarios](docs/03-usage/05-common-scenarios.md)
+- [Custom Presenters](docs/04-advanced/01-custom-presenters.md)
+- [Upgrade Guide](docs/06-upgrade-guide.md)
+- [API Reference](docs/README.md)
+
+## 🧪 Testing
 
 ```bash
 composer test
 ```
 
-## Changelog
+See the [Testing Guide](docs/05-development/01-testing.md) for more information.
+
+## 📝 Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
 
-## Contributing
+## 🤝 Contributing
 
-Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
+We welcome contributions! Please see our [Contributing Guide](docs/05-development/02-contributing.md) for details.
 
-## Security Vulnerabilities
+## 🔒 Security
 
 Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
 
-## Credits
+## 🙏 Credits
 
 - [Nasrul Hazim Bin Mohamad](https://github.com/nasrulhazim)
 - [All Contributors](../../contributors)
 
-## License
+## 📄 License
 
 The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

composer.json

@@ -17,8 +17,8 @@
     ],
     "require": {
         "php": "^8.1 | ^8.2 | ^8.3 | ^8.4",
+        "cleaniquecoders/traitify": "^1.2",
         "illuminate/contracts": "^9.0 | ^10.0 | ^11.0 | ^12.0",
-        "spatie/laravel-enum": "^3.0",
         "spatie/laravel-package-tools": "^1.14"
     },
     "require-dev": {
@@ -73,4 +73,4 @@
     },
     "minimum-stability": "dev",
     "prefer-stable": true
-}
+}

config/running-number.php

@@ -18,13 +18,7 @@
     |
     */
 
-    'types' => [
-        Organization::organization()->value,
-        Organization::division()->value,
-        Organization::section()->value,
-        Organization::unit()->value,
-        Organization::profile()->value,
-    ],
+    'types' => Organization::values(),
 
     'model' => \CleaniqueCoders\RunningNumber\Models\RunningNumber::class,
 

database/migrations/add_uuid_to_running_numbers_table.php.stub

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up()
+    {
+        Schema::table('running_numbers', function (Blueprint $table) {
+            $table->uuid('uuid')->nullable()->unique()->after('id');
+        });
+
+        // Generate UUIDs for existing records
+        $model = config('running-number.model');
+        $model::whereNull('uuid')->each(function ($record) {
+            $record->uuid = (string) \Illuminate\Support\Str::uuid();
+            $record->save();
+        });
+    }
+
+    public function down()
+    {
+        Schema::table('running_numbers', function (Blueprint $table) {
+            $table->dropColumn('uuid');
+        });
+    }
+};