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)
```

###  Alternatives

[jordanmiguel/laravel-popular

A Laravel package to track popularity of entries(by Models) in a website at a certain time.

659.6k1](/packages/jordanmiguel-laravel-popular)[jaaulde/php-ipv4

PHP classes for working with IPV4 addresses and networks.

1034.6k](/packages/jaaulde-php-ipv4)[ip2location/ip2location-cakephp

Lookup for visitor's IP information, such as country, region, city, coordinates, zip code, time zone, ISP, domain name, connection type, area code, weather, MCC, MNC, mobile brand name, elevation and usage type.

224.6k](/packages/ip2location-ip2location-cakephp)

PHPackages © 2026

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