ameax/sequence-number

A laravel package to configure and generate sequence numbers for invoices

dev-main 2024-11-21 03:55 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0||^11.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^9.0.0||^8.22.0
• pestphp/pest: ^2.34
• pestphp/pest-plugin-arch: ^2.7
• pestphp/pest-plugin-laravel: ^2.3
• phpstan/extension-installer: ^1.3
• phpstan/phpstan-deprecation-rules: ^1.1
• phpstan/phpstan-phpunit: ^1.3
• spatie/laravel-ray: ^1.35

MIT

• Michael Schmidt

• laravel
• ameax Unternehmenssoftware
• sequence-number

README

The SequenceNumber package provides an easy-to-use service for generating customizable sequence numbers. This is useful for generating unique identifiers such as invoice numbers, order IDs, or other sequences that follow a defined format.

Features

• Supports customizable prefixes, suffixes, and number lengths.
• Configurable yearly resets.
• Supports check digits for validation.
• Format sequences with custom separators and year formats.
• Includes robust database-backed sequence tracking.
• Configurable default database connection for models.

Installation

Install the package via Composer:

composer require ameax/sequence-number

Publish and run the migrations:

php artisan vendor:publish --tag="sequence-number-migrations"
php artisan migrate

Optionally, publish the configuration file:

php artisan vendor:publish --tag="sequence-number-config"

Configuration

The configuration file allows you to customize the behavior of the package. Below is the content of the config/sequence-number.php file:

return [
    'connection' => null, // Set the default connection of the Models
];

Explanation:

• connection: Defines the database connection to use for the sequences and sequence_counters models. If set to null, the default Laravel connection will be used. Set this to a specific connection name if your sequences should use a dedicated database.

Example:

return [
    'connection' => 'tenant', // Use the tenant database connection
];

Models and Fields

Sequence Model

The sequences table stores the configuration for each sequence.

SequenceCounter Model

The sequence_counters table tracks the current value of a sequence.

Usage

Generating a Sequence Number

1. Initialize the SequenceService Use the SequenceService::make() method to create a service instance.

2. Load a Sequence by Token Use the byToken(string $token) method to load a sequence by its unique token.

3. Generate the Next Sequence Number Call next() to generate the next sequence number based on the configuration.

Example:

use Ameax\SequenceNumber\Services\SequenceService;

$sequenceService = SequenceService::make()->byToken('invoice');
$nextSequence = $sequenceService->next();

echo $nextSequence; // Example: INV2023.001

Validating a Sequence Number

Use the validateSequenceNumber(string $sequenceNumber) method to validate a sequence number with a check digit.

Example:

$isValid = SequenceService::make()->byToken('invoice')->validateSequenceNumber('INV2023.001');
echo $isValid ? 'Valid' : 'Invalid';

Configuration Examples

Sequence Configuration Example

Create a sequence configuration in the sequences table:

use Ameax\SequenceNumber\Models\Sequence;

$sequence = Sequence::create([
    'token' => 'invoice',
    'prefix' => 'INV',
    'number_min_length' => 3,
    'year_format' => '4-digits',
    'year_separator' => '.',
    'use_check_digit' => true,
    'check_digit_position' => 'suffix',
    'reset_yearly' => true,
    'start_value' => 1,
]);

Testing

Example Test Scenarios

use Ameax\SequenceNumber\Models\Sequence;
use Ameax\SequenceNumber\Services\SequenceService;

// Create a sequence configuration
$sequence = Sequence::create([
    'token' => 'invoice',
    'prefix' => 'INV',
    'number_min_length' => 3,
]);

// Generate the first sequence number
expect(SequenceService::make()->byToken('invoice')->next())->toBe('INV001');

// Add a year format and separator
$sequence->update([
    'year_format' => '4-digits',
    'year_separator' => '-',
]);
expect(SequenceService::make()->byToken('invoice')->next())->toBe('INV2023-002');

Running Tests

Run all tests using Pest or PHPUnit:

composer test

Changelog

Refer to the CHANGELOG for details on recent changes.

Contributing

Contributions are welcome! Please see the CONTRIBUTING file for guidelines.

License

The MIT License (MIT). Please see the LICENSE file for more details.