PHPackages                             aldiazhar/laravel-invoice - 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. aldiazhar/laravel-invoice

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

aldiazhar/laravel-invoice
=========================

A flexible and powerful invoice management package for Laravel

014PHP

Since Nov 21Pushed 5mo agoCompare

[ Source](https://github.com/aldiazhar/invoice)[ Packagist](https://packagist.org/packages/aldiazhar/laravel-invoice)[ RSS](/packages/aldiazhar-laravel-invoice/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Laravel Invoice Package
=======================

[](#laravel-invoice-package)

A flexible and powerful invoice management package for Laravel applications.

Requirements
------------

[](#requirements)

- PHP 8.1, 8.2, or 8.3
- Laravel 10.x, 11.x, or 12.x

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

[](#installation)

```
composer require aldiazhar/laravel-invoice
```

### Publish Assets

[](#publish-assets)

```
php artisan vendor:publish --tag=invoice-config
php artisan vendor:publish --tag=invoice-migrations
php artisan migrate
```

Quick Start Guide
-----------------

[](#quick-start-guide)

### Two Ways to Create Invoice

[](#two-ways-to-create-invoice)

**Method 1: From Payer (User) Perspective**

```
$invoice = $user->invoice()
    ->pay($payment)     // What to pay
    ->create();
```

**Method 2: From Invoiceable (Payment) Perspective**

```
$invoice = $payment->bill()
    ->to($user)         // Bill to whom
    ->create();
```

Both methods create the same invoice!

### 1. Setup Models

[](#1-setup-models)

**User Model (Payer):**

```
use Aldiazhar\Invoice\Contracts\Payer;
use Aldiazhar\Invoice\Traits\HasInvoices;

class User extends Model implements Payer
{
    use HasInvoices;

    public function getPayerName(): string
    {
        return $this->name;
    }

    public function getPayerEmail(): ?string
    {
        return $this->email;
    }

    public function getPayerAddress(): ?string
    {
        return $this->address;
    }

    public function getPayerMetadata(): array
    {
        return ['phone' => $this->phone];
    }
}
```

**Payment Model (Invoiceable):**

```
use Aldiazhar\Invoice\Contracts\Invoiceable;
use Aldiazhar\Invoice\Traits\Invoiceable as InvoiceableTrait;

class Payment extends Model implements Invoiceable
{
    use InvoiceableTrait;

    public function getInvoiceableDescription(): string
    {
        return "Payment #{$this->id}";
    }

    public function getInvoiceableAmount(): float
    {
        return $this->amount;
    }

    public function getInvoiceableMetadata(): array
    {
        return [
            'payment_method' => $this->payment_method,
            'reference' => $this->reference_number,
        ];
    }

    public function onInvoicePaid($invoice): void
    {
        $this->update(['status' => 'completed']);
    }
}
```

### 2. Create Invoice

[](#2-create-invoice)

**Auto Item (Recommended - No items needed!):**

```
// From Payer perspective
$invoice = $user->invoice()
    ->pay($payment)
    ->create();

// From Invoiceable perspective
$invoice = $payment->bill()
    ->to($user)
    ->create();
```

Item otomatis dibuat dari `getInvoiceableDescription()` dan `getInvoiceableAmount()`

**Manual Single Item:**

```
$invoice = $user->invoice()
    ->pay($payment)
    ->item('Payment Processing', 100000)
    ->create();
```

**Multiple Items:**

```
$invoice = $user->invoice()
    ->pay($order)
    ->item('Product A', 50000, 2)
    ->item('Product B', 75000, 1)
    ->tax(10000)
    ->discount(5000)
    ->create();
```

**Using Array:**

```
$invoice = $user->invoice()
    ->pay($order)
    ->items([
        ['name' => 'Product A', 'price' => 50000, 'quantity' => 2, 'tax_rate' => 0.11],
        ['name' => 'Product B', 'price' => 75000, 'quantity' => 1],
    ])
    ->create();
```

**Without Auto Item (Manual Control):**

```
$invoice = $user->invoice()
    ->pay($order)
    ->withoutAutoItem()
    ->item('Custom Item', 100000)
    ->create();
```

**Advanced:**

```
$invoice = $user->invoice()
    ->pay($order)
    ->item('Premium Package', 500000)
    ->tax(20000)
    ->discount(50000)
    ->currency('USD')
    ->due('2024-12-31')
    ->description('Monthly subscription')
    ->meta(['campaign_id' => 123])
    ->after(function($invoice) {
        // Custom logic after create
    })
    ->onPaid(function($invoice) {
        // Custom logic when paid
    })
    ->create();
```

### 3. Invoice Management

[](#3-invoice-management)

```
$invoice->markAsPaid();
$invoice->cancel();
$invoice->markAsFailed();
$invoice->refund();

if ($invoice->isPaid()) {
    //
}

if ($invoice->isOverdue()) {
    //
}
```

### 4. Partial Payments

[](#4-partial-payments)

```
$invoice->addPayment(50000, 'bank_transfer', [
    'reference' => 'TRX-123',
    'notes' => 'First installment',
]);

$paidAmount = $invoice->getPaidAmount();
$remaining = $invoice->getRemainingAmount();
$isFullyPaid = $invoice->isFullyPaid();
```

### 5. Recurring Invoices

[](#5-recurring-invoices)

```
$invoice = $user->invoice()
    ->pay($subscription)
    ->item('Monthly Premium', 99000)
    ->makeRecurring('monthly', now()->addYear())
    ->create();

$schedule->command('invoices:generate-recurring')->daily();
```

### 6. Query & Statistics

[](#6-query--statistics)

```
use Aldiazhar\Invoice\Facades\Invoice;

$pending = Invoice::pending();
$paid = Invoice::paid();
$overdue = Invoice::overdue();

$stats = Invoice::stats();

$userStats = $user->getInvoiceStats();
```

### 7. Activity Log

[](#7-activity-log)

```
$activities = $invoice->activities;

foreach ($activities as $activity) {
    echo $activity->action;
    echo $activity->description;
    echo $activity->causer->name;
}
```

Auto Item Feature
-----------------

[](#auto-item-feature)

**Default Behavior (Auto Item Enabled):**

```
$payment = Payment::create(['amount' => 100000]);

$invoice = $user->invoice()
    ->pay($payment)
    ->create();
```

Secara otomatis membuat item dengan:

- Name: dari `getInvoiceableDescription()`
- Price: dari `getInvoiceableAmount()`
- Quantity: 1

**Disable Auto Item:**

```
$invoice = $user->invoice()
    ->pay($payment)
    ->withoutAutoItem()
    ->item('Custom Item', 50000)
    ->item('Another Item', 50000)
    ->create();
```

**Force Add Invoiceable Item:**

```
$invoice = $user->invoice()
    ->pay($payment)
    ->item('Extra Service', 20000)
    ->withInvoiceableItem()
    ->create();
```

Total: 120000 (100000 from payment + 20000 from extra)

Configuration
-------------

[](#configuration)

Edit `config/invoice.php`:

```
return [
    'currency' => 'USD',
    'due_date_days' => 30,
    'strict_validation' => true,

    'invoice_number' => [
        'prefix' => 'INV-',
        'format' => 'Ymd',
        'padding' => 4,
    ],
];
```

Validation
----------

[](#validation)

### Strict Mode (Default)

[](#strict-mode-default)

Invoice total must match invoiceable amount:

```
$payment = Payment::create(['amount' => 100000]);

$invoice = $user->invoice()
    ->pay($payment)
    ->create();
```

Total: 100000

```
$invoice = $user->invoice()
    ->pay($payment)
    ->item('Custom', 50000)
    ->create();
```

Error: Mismatch! Expected 100000, got 50000

### Disable Strict Mode

[](#disable-strict-mode)

```
$invoice = $user->invoice()
    ->pay($payment)
    ->item('Custom', 50000)
    ->withoutStrictValidation()
    ->create();
```

Total: 50000

API Reference
-------------

[](#api-reference)

### InvoiceBuilder Methods

[](#invoicebuilder-methods)

```
// Set who pays
->to($payer)         // Set payer (who will pay)

// Set what to pay
->pay($invoiceable)  // Set invoiceable (what to pay)

// Items
->item($name, $price, $quantity = 1, $taxRate = 0)
->items(array $items)
->withInvoiceableItem()
->withoutAutoItem()

// Amounts
->tax(float $amount)
->discount(float $amount)

// Details
->currency(string $currency)
->status(string $status)
->due($date)
->description(string $description)
->meta(array $metadata)

// Options
->withoutStrictValidation()
->makeRecurring($frequency, $endDate, $interval)

// Callbacks
->after(callable $callback)
->onPaid(callable $callback)

// Execute
->create()
```

### Invoice Methods

[](#invoice-methods)

```
$invoice->markAsPaid()
$invoice->cancel()
$invoice->markAsFailed()
$invoice->refund()
$invoice->addPayment($amount, $method, $data)
$invoice->generateNextInvoice()
$invoice->isPaid()
$invoice->isPending()
$invoice->isOverdue()
$invoice->getPaidAmount()
$invoice->getRemainingAmount()
$invoice->isFullyPaid()
```

### Query Scopes

[](#query-scopes)

```
Invoice::pending()
Invoice::paid()
Invoice::failed()
Invoice::overdue()
Invoice::forPayer($payer)
Invoice::forInvoiceable($invoiceable)
```

Examples
--------

[](#examples)

### Simple Payment Invoice (Auto Item)

[](#simple-payment-invoice-auto-item)

```
$payment = Payment::create([
    'user_id' => $user->id,
    'amount' => 150000,
    'payment_method' => 'bank_transfer',
]);

$invoice = $user->invoice()
    ->pay($payment)
    ->create();
```

Item dibuat otomatis dari payment!

### E-Commerce Order (Manual Items)

[](#e-commerce-order-manual-items)

```
$invoice = $user->invoice()
    ->pay($order)
    ->withoutAutoItem()
    ->items($order->items->map(fn($item) => [
        'name' => $item->product->name,
        'price' => $item->price,
        'quantity' => $item->quantity,
        'sku' => $item->product->sku,
    ])->toArray())
    ->tax($order->tax_amount)
    ->discount($order->discount_amount)
    ->create();
```

### Subscription (Recurring + Auto Item)

[](#subscription-recurring--auto-item)

```
$subscription = Subscription::create([
    'plan' => 'premium',
    'price' => 99000,
]);

$invoice = $user->invoice()
    ->pay($subscription)
    ->makeRecurring('monthly')
    ->onPaid(function($invoice) {
        $invoice->invoiceable->renew();
    })
    ->create();
```

### Service Payment (Mixed Items)

[](#service-payment-mixed-items)

```
$service = Service::create([
    'name' => 'Consulting',
    'base_amount' => 1200,
]);

$invoice = $user->invoice()
    ->pay($service)
    ->withInvoiceableItem()
    ->item('Travel Cost', 200)
    ->item('Materials', 100)
    ->tax(0.11)
    ->create();
```

Total: 1500 + 11% tax

Troubleshooting
---------------

[](#troubleshooting)

### Interface Implementation Issue

[](#interface-implementation-issue)

Jika muncul error "must implement Invoiceable interface", pastikan:

```
use Aldiazhar\Invoice\Contracts\Invoiceable;
use Aldiazhar\Invoice\Traits\InvoiceableTrait;

class Payment extends Model implements Invoiceable
{
    use InvoiceableTrait;

    public function getInvoiceableDescription(): string
    {
        return "Payment #{$this->id}";
    }

    public function getInvoiceableAmount(): float
    {
        return $this->amount;
    }
}
```

Jangan lupa implement semua method yang required!

### Using bill()->to() vs invoice()->pay()

[](#using-bill-to-vs-invoice-pay)

```
// These are EQUIVALENT:

// Option 1: From Payer
$user->invoice()->pay($payment)->create();

// Option 2: From Invoiceable
$payment->bill()->to($user)->create();

// Both create the same invoice!
```

### Amount Mismatch Error

[](#amount-mismatch-error)

```
$payment = Payment::create(['amount' => 100000]);

$invoice = $user->invoice()
    ->pay($payment)
    ->item('Custom', 50000)
    ->withoutStrictValidation()
    ->create();
```

Atau pastikan total items = invoiceable amount

License
-------

[](#license)

MIT License

Support
-------

[](#support)

- GitHub: [aldiazhar/laravel-invoice](https://github.com/aldiazhar/laravel-invoice)
- Issues: [GitHub Issues](https://github.com/aldiazhar/laravel-invoice/issues)

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance48

Moderate activity, may be stable

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/51ce0890960f893d3952a0236192e8c67abab0cca6251eb62cfebf920e0404cf?d=identicon)[alazhar\_pe](/maintainers/alazhar_pe)

---

Top Contributors

[![aldiazhar](https://avatars.githubusercontent.com/u/50188370?v=4)](https://github.com/aldiazhar "aldiazhar (17 commits)")

### Embed Badge

![Health badge](/badges/aldiazhar-laravel-invoice/health.svg)

```
[![Health](https://phpackages.com/badges/aldiazhar-laravel-invoice/health.svg)](https://phpackages.com/packages/aldiazhar-laravel-invoice)
```

PHPackages © 2026

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