PHPackages                             aichadigital/larabill - 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 &amp; Helpers](/categories/utility)
4. /
5. aichadigital/larabill

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

aichadigital/larabill
=====================

Professional billing &amp; invoicing package for Laravel with UUID v7, VAT verification, EU compliance, and agnostic user models (UUID/ULID/Int)

v0.6.1(1mo ago)050↓100%AGPL-3.0-or-laterPHPPHP ^8.3CI passing

Since Oct 5Pushed 1mo agoCompare

[ Source](https://github.com/AichaDigital/larabill)[ Packagist](https://packagist.org/packages/aichadigital/larabill)[ Docs](https://github.com/aichadigital/larabill)[ GitHub Sponsors](https://github.com/AichaDigital)[ RSS](/packages/aichadigital-larabill/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (22)Versions (27)Used By (0)

Larabill - Professional Billing &amp; Invoicing for Laravel
===========================================================

[](#larabill---professional-billing--invoicing-for-laravel)

[![Tests](https://camo.githubusercontent.com/262056087cfb05722ffc2c2e101c4f00b38855a541281f8b9253d74a4c660446/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f41696368614469676974616c2f6c61726162696c6c2f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/AichaDigital/larabill/actions/workflows/tests.yml)[![codecov](https://camo.githubusercontent.com/950793beb42bfbe9bd77267c886a9cf10c75d7bc652ab49f9b9ed50bb84521a3/68747470733a2f2f636f6465636f762e696f2f67682f41696368614469676974616c2f6c61726162696c6c2f6272616e63682f6d61696e2f67726170682f62616467652e7376673f7374796c653d666c61742d737175617265)](https://codecov.io/gh/AichaDigital/larabill)[![PHP Version](https://camo.githubusercontent.com/ccf0c1ca319dcf6d84fc412c70fcf6ec7d982ed218aee65ac87dace8d03c1a16/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e332d626c75653f7374796c653d666c61742d737175617265)](https://php.net)[![Laravel](https://camo.githubusercontent.com/e4229a5daad08aff9aef40146ca287d300d070c9c5f8a83bf719e2245d429dd4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d25354531312e3025323025374325323025354531322e302d7265643f7374796c653d666c61742d737175617265)](https://laravel.com)[![License](https://camo.githubusercontent.com/86183f01cb991fb8928c417560c743a85037fe6c1a33121ae9c248d49c2864b1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4147504c2d2d332e302d2d6f722d2d6c617465722d677265656e3f7374796c653d666c61742d737175617265)](LICENSE.md)

> ⚠️ **DEVELOPMENT VERSION** - This package is under active development (dev-main). Target: v1.0 stable by December 15, 2025.

Larabill is a professional, agnostic billing and invoicing package for Laravel applications. It provides comprehensive VAT verification, tax calculation for Spain/EU/worldwide, and flexible invoice generation with immutability protection.

🎯 Features
----------

[](#-features)

### Core Functionality

[](#core-functionality)

- **Invoice Management**: UUID-based IDs, sequential numbering, proforma invoices, immutable records
- **Tax Calculation**: Spanish (IVA), Canary Islands (IGIC), Ceuta/Melilla (IPSI), EU reverse charge, worldwide
- **VAT/Tax Code Verification**: Integration with AbstractAPI and APILayer for real-time validation
- **Fiscal Data Management**: Company and customer fiscal configurations with temporal validity
- **PDF Generation**: Built-in invoice PDF generation using DomPDF
- **EU Compliance**: Full support for EU B2B reverse charge and destination VAT rules

### Technical Excellence

[](#technical-excellence)

- **String UUID v7**: Ordered UUIDs for invoices (optimal for MySQL indexes)
- **Base-100 Integers**: Precise monetary calculations (no floating-point errors)
- **User Agnostic**: Works with any User model (UUID, ULID, or integer IDs)
- **Temporal Validity**: Fiscal configurations with `valid_from`/`valid_until` dates
- **Invoice Immutability**: Protection against modifications after issuance

📦 Requirements
--------------

[](#-requirements)

- PHP ^8.3
- Laravel ^11.0 | ^12.0

🚀 Installation
--------------

[](#-installation)

### Via Composer

[](#via-composer)

```
composer require aichadigital/larabill
```

### Publish Configuration

[](#publish-configuration)

```
php artisan vendor:publish --tag="larabill-config"
```

### Run the Installer

[](#run-the-installer)

```
php artisan larabill:install
```

This will:

1. Publish migrations
2. Run database migrations
3. Seed default tax categories and rates

### Manual Installation (if preferred)

[](#manual-installation-if-preferred)

```
# Publish migrations
php artisan vendor:publish --tag="larabill-migrations"

# Run migrations
php artisan migrate

# Seed default data
php artisan db:seed --class="AichaDigital\Larabill\Database\Seeders\TaxCategoriesSeeder"
php artisan db:seed --class="AichaDigital\Larabill\Database\Seeders\TaxRatesSeeder"
```

⚙️ Configuration
----------------

[](#️-configuration)

### Environment Variables

[](#environment-variables)

Add these to your `.env` file:

```
# Tax Code Verification APIs
LARABILL_ABSTRACTAPI_KEY="your_abstractapi_key"
LARABILL_APILAYER_KEY="your_apilayer_key"
LARABILL_VAT_PREFERRED_API="abstractapi"
LARABILL_VAT_CACHE_DAYS=30

# Invoice Numbering
LARABILL_INVOICE_PREFIX="FAC"
LARABILL_PROFORMA_PREFIX="PRO"

# User ID Type (auto-detected if not set)
LARABILL_USER_ID_TYPE="uuid"  # Options: uuid, int, ulid
```

### Model Configuration

[](#model-configuration)

Configure your user model in `config/larabill.php`:

```
'models' => [
    'user' => \App\Models\User::class,
    'invoice' => \AichaDigital\Larabill\Models\Invoice::class,
    'invoice_item' => \AichaDigital\Larabill\Models\InvoiceItem::class,
    // ...
],
```

🏗️ Architecture
---------------

[](#️-architecture)

### Fiscal Data Model

[](#fiscal-data-model)

Larabill separates company and customer fiscal data with temporal validity:

```
CompanyFiscalConfig    → Company fiscal settings (one active at a time)
CustomerFiscalData     → Customer fiscal data (historical per customer)
Invoice                → Immutable invoice with fiscal snapshot

```

**Key principles**:

- Company config changes apply from a specific date forward
- Customer data changes are historical (never modify past records)
- Invoices capture fiscal snapshot at creation time
- Invoices are **absolutely immutable** once issued

### UUID Strategy

[](#uuid-strategy)

Larabill uses **string UUID v7** for invoices:

```
// Model with UUID
use AichaDigital\Larabill\Concerns\HasUuid;

class Invoice extends Model
{
    use HasUuid;
}

// Migration
$table->uuid('id')->primary();
```

### Monetary Values (Base 100)

[](#monetary-values-base-100)

**All monetary values use integers in base 100** to avoid floating-point errors:

```
// €12.34 stored as:
$invoice->total_amount = 1234;

// 21% IVA stored as:
$taxRate->rate = 2100;
```

Use the `Base100Int` cast from the `lara100` package.

📖 Usage
-------

[](#-usage)

### Creating an Invoice

[](#creating-an-invoice)

```
use AichaDigital\Larabill\Services\BillingService;

$billingService = app(BillingService::class);

$invoice = $billingService->createInvoice([
    'user_id' => $user->id,
    'items' => [
        [
            'description' => 'Professional Service',
            'quantity' => 1,
            'unit_price' => 10000, // €100.00 in base 100
            'tax_rate' => 2100,    // 21% in base 100
        ]
    ]
]);
```

### Tax Calculation

[](#tax-calculation)

```
use AichaDigital\Larabill\Services\TaxCalculationService;

$taxService = app(TaxCalculationService::class);

// EU B2B reverse charge
$result = $taxService->calculateTax(10000, 'ES', 'DE', isB2B: true);
// Returns: tax_rate = 0 (reverse charge applies)

// EU B2C destination VAT
$result = $taxService->calculateTax(10000, 'ES', 'FR', isB2B: false);
// Returns: tax_rate = 2000 (20% French VAT)
```

### VAT Verification

[](#vat-verification)

```
use AichaDigital\Larabill\Services\VatVerificationService;

$vatService = app(VatVerificationService::class);

$result = $vatService->verifyVatCode('ESB12345678', 'ES');

if ($result['is_valid']) {
    echo "Valid VAT for: " . $result['company_name'];
}
```

### Company Fiscal Configuration

[](#company-fiscal-configuration)

```
use AichaDigital\Larabill\Models\CompanyFiscalConfig;

// Get current active config
$config = CompanyFiscalConfig::getActive();

// Create new config (previous becomes inactive)
$newConfig = CompanyFiscalConfig::create([
    'tax_id' => 'ESB12345678',
    'company_name' => 'Your Company S.L.',
    'address' => 'Calle Test 123',
    'city' => 'Madrid',
    'postal_code' => '28001',
    'country_code' => 'ES',
    'is_oss' => true,
    'valid_from' => now(),
]);
```

### Customer Fiscal Data

[](#customer-fiscal-data)

```
use AichaDigital\Larabill\Models\CustomerFiscalData;

// Get current fiscal data for a customer
$fiscalData = CustomerFiscalData::getActiveForUser($userId);

// Create new fiscal data (historical record)
$newData = CustomerFiscalData::createForUser($userId, [
    'tax_id' => 'FR12345678901',
    'business_name' => 'Client SARL',
    'country_code' => 'FR',
    'is_business' => true,
]);
```

🧪 Testing
---------

[](#-testing)

```
# Run all tests
composer test

# Run specific tests
composer test -- --filter=Invoice

# Run with coverage
composer test-coverage

# Static analysis
vendor/bin/phpstan analyse
```

**Current status**: 866 tests passing, 34 skipped (external dependencies)

📚 Documentation
---------------

[](#-documentation)

DocumentDescription[ARCHITECTURE.md](docs/ARCHITECTURE.md)Core architecture and domain model[CHANGELOG.md](CHANGELOG.md)Version history and breaking changes[TAX\_SYSTEM\_ANALYSIS.md](docs/TAX_SYSTEM_ANALYSIS_AND_RECOMMENDATIONS.md)Tax system design decisionsFor AI agents working with this package, see [.claude/project.md](.claude/project.md).

🗺️ Roadmap
----------

[](#️-roadmap)

### v1.0.0 (Target: December 15, 2025)

[](#v100-target-december-15-2025)

- ✅ Core invoice management
- ✅ Spanish tax system (IVA, IGIC, IPSI)
- ✅ EU reverse charge (B2B)
- ✅ Fiscal data with temporal validity
- 🔄 VeriFACTU integration (Spain AEAT)
- 🔄 WHMCS migration tools

### v2.0.0 (Future)

[](#v200-future)

- Multi-tenancy support
- Subscription billing
- Payment gateway integration (Stripe, PayPal, Redsys)
- Advanced reporting

🤝 Contributing
--------------

[](#-contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

🔒 Security
----------

[](#-security)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

📄 License
---------

[](#-license)

GNU Affero General Public License v3.0 (AGPL-3.0-or-later). See [LICENSE.md](LICENSE.md) for details.

This means:

- ✅ You can use, modify, and distribute this software
- ✅ You must share any modifications under the same license
- ⚠️ If you run this as a network service, you must provide the source code to users
- ⚠️ You must preserve copyright and attribution notices

👥 Credits
---------

[](#-credits)

- [AichaDigital](https://aichadigital.es)
- [All Contributors](../../contributors)

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance93

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor2

2 contributors hold 50%+ of commits

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 ~11 days

Recently: every ~21 days

Total

12

Last Release

36d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0a4694c48c325d3dfbc4c43d97c2617f9317d7a447971750c338f943a88bd164?d=identicon)[abkrim](/maintainers/abkrim)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (376 commits)")[![abkrim](https://avatars.githubusercontent.com/u/1238625?v=4)](https://github.com/abkrim "abkrim (209 commits)")[![mvdnbrk](https://avatars.githubusercontent.com/u/802681?v=4)](https://github.com/mvdnbrk "mvdnbrk (46 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (30 commits)")[![Nielsvanpach](https://avatars.githubusercontent.com/u/10651054?v=4)](https://github.com/Nielsvanpach "Nielsvanpach (23 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (19 commits)")[![pforret](https://avatars.githubusercontent.com/u/474312?v=4)](https://github.com/pforret "pforret (16 commits)")[![sebastiandedeyne](https://avatars.githubusercontent.com/u/1561079?v=4)](https://github.com/sebastiandedeyne "sebastiandedeyne (14 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (12 commits)")[![patinthehat](https://avatars.githubusercontent.com/u/5508707?v=4)](https://github.com/patinthehat "patinthehat (10 commits)")[![riasvdv](https://avatars.githubusercontent.com/u/3626559?v=4)](https://github.com/riasvdv "riasvdv (10 commits)")[![crynobone](https://avatars.githubusercontent.com/u/172966?v=4)](https://github.com/crynobone "crynobone (8 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (8 commits)")[![thecaliskan](https://avatars.githubusercontent.com/u/13554944?v=4)](https://github.com/thecaliskan "thecaliskan (5 commits)")[![irfanm96](https://avatars.githubusercontent.com/u/42065936?v=4)](https://github.com/irfanm96 "irfanm96 (5 commits)")[![IGedeon](https://avatars.githubusercontent.com/u/694313?v=4)](https://github.com/IGedeon "IGedeon (4 commits)")[![abenerd](https://avatars.githubusercontent.com/u/7523903?v=4)](https://github.com/abenerd "abenerd (3 commits)")[![jessarcher](https://avatars.githubusercontent.com/u/4977161?v=4)](https://github.com/jessarcher "jessarcher (3 commits)")[![koossaayy](https://avatars.githubusercontent.com/u/6431084?v=4)](https://github.com/koossaayy "koossaayy (3 commits)")[![lloricode](https://avatars.githubusercontent.com/u/8251344?v=4)](https://github.com/lloricode "lloricode (3 commits)")

---

Tags

laravelbillinguuidinvoicingb2bvattaxeuspainAichaDigitalfiscalreverse-chargelarabill

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/aichadigital-larabill/health.svg)

```
[![Health](https://phpackages.com/badges/aichadigital-larabill/health.svg)](https://phpackages.com/packages/aichadigital-larabill)
```

PHPackages © 2026

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