Laravel Numberable Laravel Package

Getting Started

Minimal Steps

1. Installation: Run composer require labrodev/numberable in your Laravel project.
2. Usage: Add the ModelHasNumber trait to any Eloquent model:

   use Labrodev\Numberable\ModelHasNumber;
   
   class Invoice extends Model
   {
       use ModelHasNumber;
   }
   

3. First Use Case: Save a new model instance. The package will automatically generate a document number (e.g., 202400001 for the first record in 2024).

Where to Look First

• Trait Documentation: Review ModelHasNumber in src/ModelHasNumber.php for default behavior.
• Customization Hook: Override generateNumberByTraitModelHasNumber() in your model for custom logic.
• Examples: Check the package’s tests/ directory for usage patterns.

Implementation Patterns

Core Workflow

1. Automatic Numbering: The trait hooks into the creating event to generate a number before saving.
2. Default Format: Uses {year}{zero-padded-ID} (e.g., 202400001).
3. Custom Logic: Override generateNumberByTraitModelHasNumber() for bespoke formats (e.g., alphanumeric, sequential letters).

Integration Tips

• Database Schema: Add a number column (e.g., string or integer) to store the generated value.
• Validation: Use Laravel’s validation rules to ensure the number field matches expected formats:

  protected $rules = [
      'number' => 'required|string|size:10', // Adjust size as needed
  ];
  

• Scopes/Queries: Add a scope to filter by number:

  public function scopeByNumber($query, $number)
  {
      return $query->where('number', $like, "%{$number}%");
  }
  

• Sequential Numbers: For non-ID-based sequences (e.g., INV-2024-001), extend the trait or use a custom generator:

  protected function generateNumberByTraitModelHasNumber(int $modelId): string
  {
      return "INV-" . now()->format('Y') . "-{$this->padZero($modelId, 3)}";
  }
  

Advanced Patterns

• Batch Processing: Disable auto-numbering during bulk inserts (e.g., migrations) by temporarily removing the trait or overriding shouldGenerateNumber():

  protected function shouldGenerateNumber(): bool
  {
      return !app()->runningUnitTests(); // Example condition
  }
  

• Soft Deletes: Ensure deleted models don’t reuse numbers by implementing a deleted_at check in generateNumberByTraitModelHasNumber().

Gotchas and Tips

Pitfalls

1. ID Collisions: If models are deleted, their IDs may be reused. Mitigate by:
   • Using a separate counter column (e.g., sequence_number).
   • Implementing a shouldGenerateNumber() guard to skip deleted models.
2. Year Rollovers: Default behavior assumes the year changes annually. For fiscal years, override the year logic:

   protected function getCurrentYear(): string
   {
       return Carbon::now()->format('Y') === '2024' ? '2025' : Carbon::now()->format('Y');
   }
   

3. Performance: Avoid complex logic in generateNumberByTraitModelHasNumber() during bulk operations (e.g., migrations).

Debugging

• Missing Numbers: Verify the number column exists and is nullable if needed.
• Incorrect Format: Check for typos in overridden methods or padding logic.
• Event Conflicts: Ensure no other creating event listeners interfere with numbering.

Extension Points

1. Custom Generators: Extend the trait to support:
   • Alphanumeric codes (e.g., ABC-2024-001).
   • Prefix/suffix logic (e.g., DOC-{year}-{id}).
2. Dynamic Prediction Numbers: Make the padding length configurable per model:

   protected int $predictionNumber = 10000; // Default
   

3. Localization: Add language-specific formats (e.g., DD/MM/YYYY-ID for non-English regions).

Config Quirks

• No Config File: The package relies entirely on trait methods. Customize behavior via model overrides.
• Thread Safety: The trait is stateless and thread-safe for Laravel’s queue workers.

Pro Tips

• Testing: Mock generateNumberByTraitModelHasNumber() in unit tests:

  $model->shouldReceive('generateNumberByTraitModelHasNumber')->andReturn('TEST123');
  

• Migration Helper: Add a number column with a default value (e.g., NULL) to avoid breaking existing records:

  Schema::table('invoices', function (Blueprint $table) {
      $table->string('number')->nullable()->after('id');
  });
  

• Documentation: Add PHPDoc comments to overridden methods for team clarity:

  /**
   * Custom number generation logic.
   * Format: INV-{year}-{3-digit-sequence}
   */
  protected function generateNumberByTraitModelHasNumber(int $modelId): string