Download the PHP package aichadigital/larabill without Composer

Larabill - Professional Billing & Invoicing for Laravel

Development happens on gitlab.castris.com. The GitHub repository is a read-only distribution mirror: issues and pull requests opened there are not seen.

🔒 Stability contract (effective from v6.0.0) — larabill is a closed, stable product governed by STABILITY.md: breaking changes only enter with a qualified, documented usage imperative; every major is auto-upgradeable from the previous one; deprecations live through at least one full major before removal. As of 6.0 the deprecated backlog is empty and there is no known future breaking change.

ℹ️ Schema upgrade policy (stable versions = respect for data) — since 1.0, larabill treats your database as a contract: schema changes ship WITH their upgrade path. Every release that touches tables includes a data-aware migration (existing rows are transformed, never discarded), and breaking majors ship an UPGRADE-X.md guide in the dist. To upgrade an existing install: composer update aichadigital/larabill, re-run php artisan larabill:install --no-migrate (idempotent — it publishes only the NEW migrations, skipping the ones you already have), then php artisan migrate. Never use migrate:fresh on a database with real data.

⚠️ Upgrading? Follow the guides sequentially: UPGRADE-6.0.md (5.x → 6.0, deprecated surface removed — zero migrations).

Larabill is a professional, UUID-first billing and invoicing package for Laravel applications. It provides tax calculation for Spain/EU/worldwide and flexible invoice generation with immutability protection, plus an optional thin bridge to intra-community VAT/NIF verification (delegated to the lararoi package). The consumer app's users.id MUST be UUID v7 char(36) — see ADR-006.

🎯 Features

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/NIF Verification (optional): thin bridge that delegates to the lararoi package (VIES and other providers). Not wired into invoice issuance — reverse charge is driven by the is_roi_taxed flag
• 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

• String UUID v7: Ordered UUIDs for invoices and the consumer's users.id (ADR-006)
• FixedDecimal money: Precise monetary value objects backed by base-100 integers (no floating-point errors)
• Preflight check: larabill:install aborts cleanly when users.id is not UUID-compatible
• Temporal Validity: Fiscal configurations with valid_from/valid_until dates
• Invoice Immutability: Protection against modifications after issuance
• Non-overlapping prices: at most one active price per article and billing frequency on any date, enforced on write (ADR-012)

📦 Requirements

• PHP ^8.3
• Laravel ^12.0 | ^13.0
• users.id UUID v7 char(36) — see docs/setup-uuid.md

🚀 Installation

Via Composer

Publish Configuration

Run the Installer

This will:

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

Diagnostic Commands

Larabill enforces at most one active price per article and billing frequency on any given date (ADR-012), and rejects writes that would break it. A database written before that invariant may already hold overlapping prices, so run this as a pre-upgrade gate and resolve what it reports. It does not repair anything on purpose: deciding which of two prices survives is a pricing decision, and it is yours.

Manual Installation (if preferred)

⚙️ Configuration

Environment Variables

Add these to your .env file:

Model Configuration

The user model resolves through user_model (env LARABILL_USER_MODEL) in config/larabill.php:

models.user is an optional explicit override — when set to an existing class it wins over user_model. If neither key points to an existing class, larabill fails loudly (no silent default). Package models can be swapped through the models block:

🏗️ Architecture

Fiscal Data Model

Larabill separates company and customer fiscal data with temporal validity:

Key principles:

• The customer is a User (ADR-003); businesses and sub-accounts are modelled with parent_user_id. The legacy CustomerFiscalData model was removed.
• Company config changes apply from a specific date forward
• UserTaxProfile records are temporally versioned (valid_from/valid_until) — never modify past records
• Invoices capture a fiscal snapshot at creation time
• Invoices are absolutely immutable once issued

UUID Strategy

Larabill uses string UUID v7 for invoices:

Monetary Values (FixedDecimal)

Money is stored as base-100 integers and exposed as FixedDecimal value objects (from lara100), so there are no floating-point errors. You assign the unscaled base-100 integer; reading the attribute returns a FixedDecimal:

Invoice and invoice-item money attributes use the FixedDecimalCast (scale 2) from the lara100 package. Note: query-builder access (->value(), ->sum(), ->where()) returns the raw integer, while Eloquent attribute access returns a FixedDecimal.

📖 Usage

Creating an Invoice

Invoice numbers are correlative per series (invoice_series_control, EU/RD 1619/2012): fiscal_number, prefix, series_number and fiscal_year all derive atomically from InvoiceNumberingService. An active CompanyFiscalConfig must exist — createInvoice() snapshots the issuer's fiscal data and refuses to emit without it.

Removed in 6.0: the former BillingService quick-start path is gone — InvoiceService is the emission path. See UPGRADE-6.0.md for the 1:1 mapping.

Tax Calculation

VAT/NIF Verification (optional bridge to lararoi)

Intra-community VAT/NIF verification is owned by the lararoi package. Larabill exposes a single thin bridge action that delegates to lararoi's contract and returns its canonical result unchanged:

Providers (VIES, isvat, vatlayer, …), caching and optional tracking are configured in lararoi, not here — publish its config with php artisan vendor:publish --tag="lararoi-config". This bridge is not wired into invoice issuance: reverse charge is decided by the invoice's is_roi_taxed flag, never by a live lookup.

Company Fiscal Configuration

User Tax Profile

The customer is a User (ADR-003); their fiscal data lives in UserTaxProfile, temporally versioned. This replaces the removed CustomerFiscalData model.

🧪 Testing

Current status (v3.1.3): 928 tests passing on SQLite, plus MySQL 8 integration tests (real column types and unique constraints) and fork-based concurrency tests. The UUID-first contract is demonstrated on MySQL 8.

📚 Documentation

For AI agents working with this package, see .claude/project.md.

🗺️ Roadmap

Shipped

• ✅ Core invoice management (immutable records, UUID v7, sequential numbering, proforma)
• ✅ Spanish tax system (IVA, IGIC, IPSI)
• ✅ EU reverse charge (B2B) and destination VAT
• ✅ Fiscal data with temporal validity (CompanyFiscalConfig, UserTaxProfile)
• ✅ FixedDecimal money type (base-100, no floating-point errors)
• ✅ VeriFACTU integration (Spain AEAT) via lara-verifactu
• ✅ Grouped payments
• ✅ Legal-retention contract (LegallyRetainable) for GDPR tooling

Under consideration

• Subscription billing
• Payment gateway integration (Stripe, PayPal, Redsys)
• Advanced reporting

See the CHANGELOG for the full release history.

🤝 Contributing

Please see CONTRIBUTING for details.

🔒 Security

Please review our security policy on how to report security vulnerabilities.

📄 License

GNU Affero General Public License v3.0 (AGPL-3.0-or-later). See 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

• AichaDigital
• All Contributors