#Order numbers

#Configuring order numbers

Larasell uses the SequentialOrderNumberGenerator by default. It generates order numbers from an incrementing sequence.

You can configure it inside config/larasell.php.

#Changing the prefix

By default, Larasell uses the LS- prefix for each order number. To change this, add a prefix value to the configuration:

1use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;
2
3return [
4  'order_numbers' => [
5      'generator' => SequentialOrderNumberGenerator::class,
6      'prefix' => 'SHOP-',
7  ],
8];

Setting a different prefix changes the order number from LS-000001 to SHOP-000001. Doing so only affects future order numbers. Existing order numbers stay the same.

#Changing the suffix

You can also change the suffix. This is useful, for example, when you run multiple stores in different regions and want the order number to reflect where the order was placed:

1use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;
2
3return [
4  'order_numbers' => [
5      'generator' => SequentialOrderNumberGenerator::class,
6      'suffix' => '-EU',
7  ],
8];

The order number then looks like this: LS-000001-EU. Changing the suffix only affects new order numbers. So changing the suffix to -US would generate LS-000002-US, keep this in mind.

#Changing the padding

By default, each order number has 6 digits, so every order number has the same length.

To change the length, change the padding value in the config/larasell.php file:

1use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;
2
3return [
4  'order_numbers' => [
5      'generator' => SequentialOrderNumberGenerator::class,
6      'padding' => 4,
7  ]
8];

Now every new order will have 4 digits, like LS-0001.

Once you pass 999999, the length increases by one and every new order number will have 7 digits. All previous order numbers keep their 6 digit format.

#Disabling the padding

To disable the padding set the padding to null:

1use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;
2
3return [
4  'order_numbers' => [
5      'generator' => SequentialOrderNumberGenerator::class,
6      'padding' => null,
7  ]
8];

Now, each order number has the amount of digits it needs i.e. LS-1, LS-2, LS-10, LS-100 and so forth.

#Changing the start number

The first order number starts at 1, e.g. LS-000001. To change the start number, edit the start value in config/larasell.php:

1use Larasell\Larasell\OrderNumbers\SequentialOrderNumberGenerator;
2
3return [
4  'order_numbers' => [
5      'generator' => SequentialOrderNumberGenerator::class,
6      'start' => 1000,
7  ],
8];

When the start number is higher than the last order number, the generator skips the numbers in between. When the start number is lower, the sequence continues from the last order number.

#Creating a custom generator

When you outgrow the default generator, replace it with a custom one.

You might use an external service or Redis to generate order numbers or need multiple sequences, for example a sequence that resets for the new year.

Create a new generator using the CLI:

1php artisan make:order-number-generator CustomOrderNumberGenerator

That command writes the class to app/OrderNumbers/Generators. This one takes the next integer from the single sequence and returns ORD-1, then ORD-2:

 1namespace App\OrderNumbers\Generators;
 2
 3use Larasell\Larasell\Contracts\OrderNumberGenerator;
 4use Larasell\Larasell\OrderNumbers\SingleOrderNumberSequence;
 5
 6class CustomOrderNumberGenerator implements OrderNumberGenerator
 7{
 8    public function __construct(private readonly SingleOrderNumberSequence $sequence) {}
 9
10    public function generate(): string
11    {
12        $next = $this->sequence->next();
13
14        return 'ORD-'.$next;
15    }
16}

Finally, register that class as the generator:

1use App\OrderNumbers\Generators\CustomOrderNumberGenerator;
2
3return [
4  'order_numbers' => [
5      'generator' => CustomOrderNumberGenerator::class,
6  ],
7];

#Using multiple sequences

By default, Larasell generates order numbers using a single sequence that starts at 1 and counts upwards.

Changing the prefix or suffix leaves the counter running. For example, when you change the suffix from -2025 to -2026, the counter simply continues: the next order number will be LS-000456-2026 instead of LS-000001-2026.

Some stores need that, though. They need order numbers to start over (yearly reset) or count upwards independently (separate sequence for each country).

To help with that Larasell provides a MultipleOrderNumberSequence class. Run php artisan make:order-number-generator YearlyOrderNumberGenerator, then replace the generated method so each year has its own sequence:

 1namespace App\OrderNumbers\Generators;
 2
 3use Illuminate\Support\Str;
 4use Larasell\Larasell\Contracts\OrderNumberGenerator;
 5use Larasell\Larasell\OrderNumbers\MultipleOrderNumberSequence;
 6
 7class YearlyOrderNumberGenerator implements OrderNumberGenerator
 8{
 9    public function __construct(private readonly MultipleOrderNumberSequence $sequences) {}
10
11    public function generate(): string
12    {
13        $year = now()->format('Y');
14
15        $next = $this->sequences->next('year-'.$year);
16
17        return 'ORD-'.$year.'-'.Str::padLeft($next, 6, '0'); // e.g. ORD-2026-000001
18    }
19}

Larasell stores each sequence by name, so a new name like year-2026 starts counting from the beginning again.