PHPackages                             yeeraf/laravel-document-numberer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. yeeraf/laravel-document-numberer

ActiveLibrary[Utility & Helpers](/categories/utility)

yeeraf/laravel-document-numberer
================================

A Laravel package for create document running number

v1.4.0(1w ago)21.5k↓68.6%MITPHPPHP ^8.0

Since Jul 24Pushed 1y ago1 watchersCompare

[ Source](https://github.com/yeeraf/laravel-document-numberer)[ Packagist](https://packagist.org/packages/yeeraf/laravel-document-numberer)[ RSS](/packages/yeeraf-laravel-document-numberer/feed)WikiDiscussions main Synced 3d ago

READMEChangelog (2)Dependencies (4)Versions (5)Used By (0)

Test Status
-----------

[](#test-status)

[![Test](https://github.com/yeeraf/laravel-document-numberer/actions/workflows/test.yml/badge.svg)](https://github.com/yeeraf/laravel-document-numberer/actions/workflows/test.yml)

Laravel Document Running Number Generator
=========================================

[](#laravel-document-running-number-generator)

A Laravel package for generating sequential document numbers with a customisable prefix, suffix, and padding. Ideal for invoices, receipts, quotations, and any document that requires a unique running number.

Examples:

- INV-000001
- INV2101-0001
- REC-0000001
- QT #####1

Concurrent requests are safe — the package uses database row-level locking and a unique constraint to guarantee no two requests ever receive the same number.

Installation
------------

[](#installation)

```
composer require yeeraf/laravel-document-numberer
```

Then run the migration to create the `document_numbers` table:

```
php artisan migrate
```

Basic Usage
-----------

[](#basic-usage)

```
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->generate();
// "2107000001"
```

By default the number is prefixed with the last 2 digits of the current year and the 2-digit month — e.g. for 20/07/2021 the prefix is **2107** — followed by a 6-digit zero-padded sequence starting at 1: 2107**000001**.

Options
-------

[](#options)

### `name()` — separate counters per document type

[](#name--separate-counters-per-document-type)

Use this when two document types share the same format but must have independent sequences.

```
// Invoice counter
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->name("invoice")->generate();
// "2107000001"

// Receipt counter (independent from invoice)
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->name("receipt")->generate();
// "2107000001"
```

### `prefix()` — custom prefix

[](#prefix--custom-prefix)

```
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->prefix("INV-")->generate();
// "INV-000001"
```

### `suffix()` — custom suffix

[](#suffix--custom-suffix)

```
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->suffix("-X")->generate();
// "2107000001-X"
```

### `padLength(int)` — number of digits in the sequence

[](#padlengthint--number-of-digits-in-the-sequence)

```
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->padLength(3)->generate();
// "2107001"
```

### `padString()` — character used for padding

[](#padstring--character-used-for-padding)

```
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->padString("#")->generate();
// "2107#####1"
```

### `padType()` — padding direction (`left` or `right`)

[](#padtype--padding-direction-left-or-right)

Default is `left` (digits appear on the right).

```
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->padType('right')->generate();
// "2107100000"
```

### `teamId()` — separate counters per team

[](#teamid--separate-counters-per-team)

Use in multi-tenant applications where each team needs its own independent sequence.

```
// Team 1
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->teamId(1)->generate();
// "2107000001"

// Team 2 (independent counter)
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer->teamId(2)->generate();
// "2107000001"
```

### `autoExtend()` — prevent the sequence from exceeding `padLength`

[](#autoextend--prevent-the-sequence-from-exceeding-padlength)

Default is `true` (the sequence grows beyond `padLength` automatically).

Set to `false` to throw an exception once the sequence would exceed the configured length:

```
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer
                ->padLength(3)
                ->autoExtend(false)
                ->generate();
// throws Exception("running number length go over pad length") once the counter exceeds 999
```

Combined Example
----------------

[](#combined-example)

```
$documentNumberer = new \Yeeraf\DocumentNumberer\DocumentNumberer;
$docNumber = $documentNumberer
                ->name("invoice")
                ->prefix("INV-")
                ->suffix("-X")
                ->padLength(4)
                ->padString("_")
                ->padType("left")
                ->teamId(1)
                ->generate();
// "INV-___1-X"
```

Concurrency
-----------

[](#concurrency)

The package uses `SELECT ... FOR UPDATE` (row-level locking) together with a unique composite index on the `document_numbers` table to prevent race conditions when multiple requests call `generate()` simultaneously.

- **Unique index** — prevents duplicate rows from being created when two requests initialise the same counter at the same time.
- **Deadlock retry** — if MySQL raises a deadlock error, the transaction is automatically retried up to 3 times.

> **Note:** `SELECT ... FOR UPDATE` is supported by MySQL and PostgreSQL only. SQLite (used in the test suite) silently ignores this clause. Run the test suite against MySQL to validate concurrency behaviour.

License
-------

[](#license)

The MIT License (MIT)

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance63

Regular maintenance activity

Popularity22

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 81.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~599 days

Total

4

Last Release

7d ago

PHP version history (2 changes)v1.1.0PHP ^7.4|^8.0

v1.4.0PHP ^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/945179?v=4)[Mn](/maintainers/mininoz)[@mininoz](https://github.com/mininoz)

---

Top Contributors

[![mininoz](https://avatars.githubusercontent.com/u/945179?v=4)](https://github.com/mininoz "mininoz (36 commits)")[![suphasits](https://avatars.githubusercontent.com/u/124806758?v=4)](https://github.com/suphasits "suphasits (8 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/yeeraf-laravel-document-numberer/health.svg)

```
[![Health](https://phpackages.com/badges/yeeraf-laravel-document-numberer/health.svg)](https://phpackages.com/packages/yeeraf-laravel-document-numberer)
```

###  Alternatives

[metabor/statemachine

Statemachine in PHP 8.2+

103150.9k3](/packages/metabor-statemachine)[nethergamesmc/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

153.7k4](/packages/nethergamesmc-bedrock-protocol)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)