README

Beautiful, type-safe PDF invoice generator for Laravel 12+ with a fluent builder API, multiple professional templates, and multi-language support.

Features

Builder Pattern - Chainable, fluent API for creating invoices
Type-Safe - Strict types, readonly DTOs, zero magic
Carbon Support - Seamless Carbon and CarbonImmutable integration for Laravel 11+
3 Templates - Minimal, modern, and branded designs (Tailwind CSS)
Multi-Language - English, Portuguese, French (easily extensible)
Custom Fields - Add any custom attributes to entities
Currency Support - Flexible formatting with Laravel integration
Multiple PDF Engines - Choose between Spatie (Puppeteer) or DomPDF
Fully Tested - Comprehensive PestPHP test suite
Quality Tools - PHPStan level max, Laravel Pint, Rector

Installation

Install via Composer:

composer require akira/laravel-pdf-invoices

Choose your PDF generation engine:

Option 1: Spatie (Puppeteer) - Default

Best for complex layouts and JavaScript rendering:

npm install puppeteer

Option 2: DomPDF

Pure PHP solution, no Node.js required:

# DomPDF is included as a dependency, no additional steps needed

Then publish assets:

php artisan vendor:publish --provider="Akira\PdfInvoices\PdfInvoicesServiceProvider"

Configure your PDF engine in .env:

# Use 'spatie' (default) or 'dompdf'
INVOICES_PDF_DRIVER=spatie

Learn more about PDF generators →

Quick Start

use Akira\PdfInvoices\Builders\InvoiceBuilder;
use Akira\PdfInvoices\Builders\EntityBuilder;
use Akira\PdfInvoices\Builders\ItemBuilder;

$invoice = InvoiceBuilder::make()
    ->seller(
        EntityBuilder::make()
            ->name('Your Company')
            ->address('123 Main St, City')
            ->email('hello@company.com')
            ->vat('123456789')
            ->build()
    )
    ->buyer(
        EntityBuilder::make()
            ->name('Client Name')
            ->email('client@example.com')
            ->address('456 Oak Ave, Town')
            ->vat('987654321')
            ->build()
    )
    ->addItem(
        ItemBuilder::make()
            ->description('Professional Services')
            ->unitPrice(150)
            ->quantity(10)
            ->tax(0.19)
            ->build()
    )
    ->addItem(
        ItemBuilder::make()
            ->description('Support & Maintenance')
            ->unitPrice(100)
            ->quantity(5)
            ->tax(0.19)
            ->discount(0.10)
            ->build()
    )
    ->locale('en')
    ->notes('Payment due within 30 days.')
    ->build();

// Generate and save PDF
$pdf = $invoice->generatePdf();
$pdf->save('invoices/invoice-001.pdf');

// Or get as stream (for downloads/email)
return response()->streamDownload(
    fn() => echo $pdf,
    'invoice-001.pdf'
);

Templates

Choose your preferred invoice style:

Minimal

Clean and simple, perfect for service invoices.

Modern

Contemporary design with gradient header and professional layout.

Branded

Business-focused with color accents for custom branding.

// Use a specific template
$pdf = $invoice->generatePdf(template: 'branded');

Localization

Generate invoices in different languages by setting the locale in the builder:

// Portuguese invoice
$invoice = InvoiceBuilder::make()
    ->locale('pt')
    // ... other methods
    ->build();

// French invoice
$invoice = InvoiceBuilder::make()
    ->locale('fr')
    // ... other methods
    ->build();

// English invoice (default)
$invoice = InvoiceBuilder::make()
    ->locale('en')
    // ... other methods
    ->build();

Supported: English (en), Portuguese (pt), French (fr)

View all translation keys →

Custom Attributes

Add custom fields to any entity:

$seller = EntityBuilder::make()
    ->name('Company')
    ->withAttributes([
        'bank_account' => 'IBAN123456',
        'registration' => 'REG-123',
    ])
    ->build();

// Access them
$seller->attributes('bank_account'); // IBAN123456

Currency Formatting

Use Laravel's currency or custom formatters:

// Laravel currency (respects app.php locale)
$invoice->currency = 'EUR';

// Custom currency symbol
$invoice->currency = '$';

Storage

Save invoices to disk or custom storage:

// Save to storage/app/invoices
$storage = app(\Akira\PdfInvoices\Contracts\StorageDriverContract::class);
$storage->save('invoice-001.pdf', $pdf);

// Or use Laravel Storage facade directly
\Illuminate\Support\Facades\Storage::put('invoices/invoice-001.pdf', $pdf);

Advanced Usage

Discounts & Taxes

ItemBuilder::make()
    ->description('Service')
    ->unitPrice(1000)
    ->quantity(2)
    ->tax(0.19)           // 19% tax
    ->discount(0.10)      // 10% discount on subtotal
    ->build()

Custom Invoice Numbers & Dates

$invoice = InvoiceBuilder::make()
    ->invoiceNumber('INV-2024-001')
    ->issuedAt(now())
    ->dueAt(now()->addDays(30))
    // ...
    ->build();

Carbon & CarbonImmutable Support

The date methods accept both Carbon (mutable) and CarbonImmutable (immutable) instances, as well as any DateTimeInterface implementation. This makes it seamless to work with Laravel 11+ which uses CarbonImmutable by default:

// All of these work seamlessly:
$invoice->issuedAt(Carbon::now());              // Mutable Carbon
$invoice->issuedAt(now());                      // CarbonImmutable (Laravel default)
$invoice->issuedAt(new DateTime('2024-01-01')); // DateTime
$invoice->issuedAt($model->created_at);         // Eloquent model attribute (CarbonImmutable)

Accessing Calculations

$invoice->getSubtotal();      // Sum of all items
$invoice->getTotalTax();      // Total tax amount
$invoice->getTotalDiscount(); // Total discount amount
$invoice->getTotal();         // Final amount due

Testing

Run the test suite:

composer test

With coverage:

composer test -- --coverage

Documentation

Changelog

See CHANGELOG.md for recent changes and updates.

License

The MIT License (MIT). See LICENSE.md for details.

Credits

Built with Laravel best practices and inspired by the Laravel community.

Kidiatoliny - Creator
All Contributors

Support

Having issues? Check out the documentation or open an issue on GitHub.

akira/laravel-pdf-invoices

包简介

关键字：

README 文档