README

A Laravel package for generating unique invoice numbers with customizable prefixes and auto-incrementing sequences.

Features

Generate unique invoice numbers (e.g., INV-2505-0001, ORD-2505-0002)
Customizable prefixes for different document types
Auto-incrementing sequence numbers
Monthly/yearly reset options
Database-backed sequence tracking
Laravel 11+ support
Comprehensive test coverage
Artisan command included

Requirements

PHP ^8.2
Laravel ^11.0

Installation

Install the package via Composer:

composer require your-vendor/invoice-generator

Publish the configuration file:

php artisan vendor:publish --tag=invoice-generator-config

Publish and run the migration:

php artisan vendor:publish --tag=invoice-generator-migrations
php artisan migrate

Configuration

The configuration file config/invoice-generator.php allows you to customize:

return [
    'default_prefix' => 'INV',
    
    'prefixes' => [
        'invoice' => 'INV',
        'order' => 'ORD',
        'quote' => 'QUO',
    ],
    
    'format' => [
        'separator' => '-',
        'year_format' => 'y',    // 'Y' for 2025, 'y' for 25
        'month_format' => 'm',   // 'm' for 05, 'n' for 5
        'number_padding' => 4,   // Number of digits
    ],
    
    'reset_period' => 'monthly', // 'yearly', 'monthly', 'never'
];

Usage

Basic Usage

use Devomar2\InvoiceGenerator\Contracts\InvoiceGeneratorInterface;

// Generate with default prefix
$generator = app(InvoiceGeneratorInterface::class);
$invoice = $generator->generate(); // INV-2505-0001

// Generate with custom prefix
$order = $generator->generate('ORD'); // ORD-2505-0001

// Generate for specific date
$date = new DateTime('2025-12-15');
$invoice = $generator->generate('INV', $date); // INV-2512-0001

Facade Usage (Optional)

You can create a facade for easier access:

// Create app/Facades/InvoiceGenerator.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

class InvoiceGenerator extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'invoice-generator';
    }
}

// Usage
$invoice = \App\Facades\InvoiceGenerator::generate('INV');

Artisan Command

Generate invoices from the command line:

# Generate one invoice
php artisan invoice:generate

# Generate with custom prefix
php artisan invoice:generate --prefix=ORD

# Generate multiple invoices
php artisan invoice:generate --count=5

# Generate for specific date
php artisan invoice:generate --date=2025-12-31

Events

The package dispatches an event when an invoice is generated:

use Devomar2\InvoiceGenerator\Events\InvoiceGenerated;
use Illuminate\Support\Facades\Event;

Event::listen(InvoiceGenerated::class, function ($event) {
    // $event->invoiceNumber
    // $event->prefix
    // $event->date
});

Testing

Run the package tests:

composer test

Run with coverage:

composer test-coverage

Development

Setting Up for Development

Clone the repository
Install dependencies: composer install
Copy .env.example to .env
Run tests: composer test

Code Style

The package follows PSR-12 coding standards. Run PHP-CS-Fixer:

composer fix-style

License

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

Contributing

Please see CONTRIBUTING.md for details.

Security

If you discover any security related issues, please email hi@devomar.me instead of using the issue tracker.

devomar-2 / invoice-generator

Maintainers

Details