Laravel Invoices

https://github.com/laraveldaily/laravel-invoices
Admin
Laravel Invoices is a Laravel package that provides an easy-to-use interface to generate Invoice PDF...
Tokens:60,944
Snippets:416
Trust Score:8.5
License:GPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### download usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Example usage of download, returning the PDF as a download response.

```php
return $invoice->download(); // browser saves the PDF
```

--------------------------------

### Advanced invoice creation with Party, items, and full configuration

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/README.md

Advanced usage example. Creates seller and buyer parties, multiple invoice items with various discounts and units, custom notes, and an invoice with many configuration options (series, sequence, currency, dates, logo). Saves the invoice to the 'public' disk, gets its URL, and streams it to the browser.

```php
use LaravelDaily\Invoices\Invoice;
use LaravelDaily\Invoices\Classes\Party;
use LaravelDaily\Invoices\Classes\InvoiceItem;

// ...

$client = new Party([
    'name'          => 'Roosevelt Lloyd',
    'phone'         => '(520) 318-9486',
    'custom_fields' => [
        'note'        => 'IDDQD',
        'business id' => '365#GG',
    ],
]);

$customer = new Party([
    'name'          => 'Ashley Medina',
    'address'       => 'The Green Street 12',
    'code'          => '#22663214',
    'custom_fields' => [
        'order number' => '> 654321 <',
    ],
]);

$items = [
    InvoiceItem::make('Service 1')
        ->description('Your product or service description')
        ->pricePerUnit(47.79)
        ->quantity(2)
        ->discount(10),
    InvoiceItem::make('Service 2')->pricePerUnit(71.96)->quantity(2),
    InvoiceItem::make('Service 3')->pricePerUnit(4.56),
    InvoiceItem::make('Service 4')->pricePerUnit(87.51)->quantity(7)->discount(4)->units('kg'),
    InvoiceItem::make('Service 5')->pricePerUnit(71.09)->quantity(7)->discountByPercent(9),
    InvoiceItem::make('Service 6')->pricePerUnit(76.32)->quantity(9),
    InvoiceItem::make('Service 7')->pricePerUnit(58.18)->quantity(3)->discount(3),
    InvoiceItem::make('Service 8')->pricePerUnit(42.99)->quantity(4)->discountByPercent(3),
    InvoiceItem::make('Service 9')->pricePerUnit(33.24)->quantity(6)->units('m2'),
    InvoiceItem::make('Service 11')->pricePerUnit(97.45)->quantity(2),
    InvoiceItem::make('Service 12')->pricePerUnit(92.82),
    InvoiceItem::make('Service 13')->pricePerUnit(12.98),
    InvoiceItem::make('Service 14')->pricePerUnit(160)->units('hours'),
    InvoiceItem::make('Service 15')->pricePerUnit(62.21)->discountByPercent(5),
    InvoiceItem::make('Service 16')->pricePerUnit(2.80),
    InvoiceItem::make('Service 17')->pricePerUnit(56.21),
    InvoiceItem::make('Service 18')->pricePerUnit(66.81)->discountByPercent(8),
    InvoiceItem::make('Service 19')->pricePerUnit(76.37),
    InvoiceItem::make('Service 20')->pricePerUnit(55.80),
];

$notes = [
    'your multiline',
    'additional notes',
    'in regards of delivery or something else',
];
$notes = implode("<br>", $notes);

$invoice = Invoice::make('receipt')
    ->series('BIG')
    // ability to include translated invoice status
    // in case it was paid
    ->status(__('invoices::invoice.paid'))
    ->sequence(667)
    ->serialNumberFormat('{SEQUENCE}/{SERIES}')
    ->seller($client)
    ->buyer($customer)
    ->date(now()->subWeeks(3))
    ->dateFormat('m/d/Y')
    ->payUntilDays(14)
    ->currencySymbol('$')
    ->currencyCode('USD')
    ->currencyFormat('{SYMBOL}{VALUE}')
    ->currencyThousandsSeparator('.')
    ->currencyDecimalPoint(',')
    ->filename($client->name . ' ' . $customer->name)
    ->addItems($items)
    ->notes($notes)
    ->logo(public_path('vendor/invoices/sample-logo.png'))
    // You can additionally save generated invoice to configured disk
    ->save('public');

$link = $invoice->url();
// Then send email to party with link

// And return invoice itself to browser or have a different view
return $invoice->stream();
```

--------------------------------

### applyQuantity usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/pricing-service.md

Example call to applyQuantity with a fractional quantity and expected result.

```php
PricingService::applyQuantity(25.55, 0.5, 2); // 12.78
```

--------------------------------

### Usage Examples

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice-item.md

Examples of creating invoice items with various pricing, discount, and tax options.

```APIDOC
## Usage Examples

### Basic
```php
use LaravelDaily\Invoices\Classes\InvoiceItem;

$items = [
    InvoiceItem::make('Service 1')
        ->description('Your product or service description')
        ->pricePerUnit(47.79)
        ->quantity(2)
        ->discount(10),                      // absolute discount in currency
    InvoiceItem::make('Service 4')
        ->pricePerUnit(87.51)
        ->quantity(7)
        ->discount(4)
        ->units('kg'),
    InvoiceItem::make('Service 5')
        ->pricePerUnit(71.09)
        ->quantity(7)
        ->discountByPercent(9)               // 9% discount
        ->taxByPercent(8),                   // 8% tax
];
```

### Error handling
```php
try {
    $item->discount(5);
    $item->discountByPercent(3); // throws: "InvoiceItem: unable to set discount twice."
} catch (\Exception $e) {
    // $e->getMessage() === 'InvoiceItem: unable to set discount twice.'
}
```

### Manual subtotal (no auto math)
```php
$item = InvoiceItem::make('Fixed price')->subTotalPrice(100.0);
// $item->calculate($decimals) returns immediately; sub_total_price stays 100.0
```
```

--------------------------------

### applyTax usage examples

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/pricing-service.md

Example calls to applyTax showing additive and percentage modes with expected results.

```php
PricingService::applyTax(49.99856, 10.11111, 2);    // 60.11
PricingService::applyTax(49.99, 21, 2, true);       // 60.49
```

--------------------------------

### InstallCommand: invoices:install signature and handle()

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/provider-and-commands.md

Defines the invoices:install command signature, description, and handle() method. Running the command publishes the invoices.assets, invoices.views, invoices.translations, and invoices.config tags via vendor:publish, then prints 'Invoices scaffolding installed successfully.'

```php
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'invoices:install';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Install all of the Invoices resources';

    /**
     * Execute the console command.
     *
     * @return void
     */
    public function handle()
```

```bash
$ php artisan invoices:install
```

--------------------------------

### Typical Usage Example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Example of creating an invoice with a buyer, item, discount, tax, shipping, and streaming the result.

```APIDOC
## Typical Usage

### Description
Example of using the Invoice class with fluent methods to create an invoice and return it as a stream.

### Code Example
```php
use LaravelDaily\Invoices\Invoice;
use LaravelDaily\Invoices\Classes\Buyer;
use LaravelDaily\Invoices\Classes\InvoiceItem;

$customer = new Buyer(['name' => 'John Doe', 'custom_fields' => ['email' => 'test@example.com']]);
$item     = InvoiceItem::make('Service 1')->pricePerUnit(2);

$invoice = Invoice::make()
    ->buyer($customer)
    ->discountByPercent(10)
    ->taxRate(15)
    ->shipping(1.99)
    ->addItem($item);

return $invoice->stream();
```
```

--------------------------------

### render usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Example usage of render, showing that after the call the pdf and output properties are populated.

```php
$invoice->render(); // $invoice->pdf and $invoice->output are now populated
```

--------------------------------

### applyDiscount usage examples

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/pricing-service.md

Example calls to applyDiscount showing subtractive and percentage modes with expected results.

```php
PricingService::applyDiscount(49.99, 9.555, 2);        // 40.44
PricingService::applyDiscount(49.99, 15.666, 2, true); // 42.16
```

--------------------------------

### Create a Buyer instance

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/party.md

Example of constructing a Buyer instance with a properties array. The constructor must be passed the properties array.

```php
$customer = new Buyer([
    'name'          => 'Ashley Medina',
    'address'       => 'The Green Street 12',
    'code'          => '#22663214',
    'custom_fields' => ['order number' => '> 654321 <'],
]);
```

--------------------------------

### DateFormatter usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-formatters.md

Shows how to set the date, date format, and pay-until days, then retrieve the formatted dates.

```php
$invoice->date(now()->subWeeks(3))->dateFormat('m/d/Y')->payUntilDays(14);
$invoice->getDate();         // e.g. "09/03/2025"
$invoice->getPayUntilDate(); // issue date + 14 days
```

--------------------------------

### InvoiceItem::make usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice-item.md

Example of creating an InvoiceItem with a title and setting a price per unit.

```php
$item = InvoiceItem::make('Service 1')->pricePerUnit(2);
```

--------------------------------

### toHtml usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Example usage of toHtml, returning the HTML view response for browser display.

```php
return $invoice->toHtml(); // view response in a browser
```

--------------------------------

### Set and get custom data with setCustomData and getCustomData

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Attaches arbitrary user data to the invoice and retrieves it. The example shows setting a reference and then getting the same array back.

```php
$invoice->setCustomData(['reference' => 'PO-1234']);
$value = $invoice->getCustomData(); // ['reference' => 'PO-1234']
```

--------------------------------

### Publish Laravel Invoices resources with invoices:install

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/README.md

Publish assets, views, translations, and config for Laravel Invoices after installation.

```bash
$ php artisan invoices:install
```

--------------------------------

### addItem usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Example usage of addItem, creating an InvoiceItem with a price per unit and adding it to the invoice.

```php
$invoice->addItem(InvoiceItem::make('Service 1')->pricePerUnit(2));
```

--------------------------------

### addItems usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Example usage of addItems, adding multiple InvoiceItem instances in a single call.

```php
$invoice->addItems([
    InvoiceItem::make('A')->pricePerUnit(10),
    InvoiceItem::make('B')->pricePerUnit(20),
]);
```

--------------------------------

### Basic invoice creation with Buyer and InvoiceItem

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/README.md

Basic usage example from RandomController.php. Creates a buyer, an invoice item, and an invoice with discount, tax, and shipping, then streams the PDF to the browser.

```php
use LaravelDaily\Invoices\Invoice;
use LaravelDaily\Invoices\Classes\Buyer;
use LaravelDaily\Invoices\Classes\InvoiceItem;

// ...

$customer = new Buyer([
    'name'          => 'John Doe',
    'custom_fields' => [
        'email' => 'test@example.com',
    ],
]);

$item = InvoiceItem::make('Service 1')->pricePerUnit(2);

$invoice = Invoice::make()
    ->buyer($customer)
    ->discountByPercent(10)
    ->taxRate(15)
    ->shipping(1.99)
    ->addItem($item);

return $invoice->stream();
```

--------------------------------

### Facade usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/provider-and-commands.md

Shows facade usage for low-traffic flows: create a party, an item, and an invoice, then stream the result. The facade targets a singleton instance, so persistent state carries over across expressions.

```php
use Invoice;

$customer = Invoice::makeParty(['name' => 'John Doe']);
$item     = Invoice::makeItem('Your service or product title')->pricePerUnit(9.99);
return Invoice::make()->buyer($customer)->addItem($item)->stream();
```

--------------------------------

### stream usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Typical controller usage of stream, chaining invoice creation and returning the streamed PDF response.

```php
// Typical controller return:
return Invoice::make()->buyer($customer)->addItem($item)->stream();
```

--------------------------------

### stream error handling example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Error handling example for stream, catching exceptions and returning back with error messages.

```php
try {
    $response = $invoice->stream();
} catch (\Exception $e) {
    // e.g. "Buyer not defined." / "No items to invoice defined."
    return back()->withErrors(['invoice' => $e->getMessage()]);
}
```

--------------------------------

### SerialNumberFormatter usage example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-formatters.md

Shows how to set series, sequence, and serial number format, then retrieve the serial number.

```php
$invoice->series('BIG')->sequence(667)->serialNumberFormat('{SEQUENCE}/{SERIES}');
$invoice->getSerialNumber(); // "00667/BIG"
```

--------------------------------

### Manual override example

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Shows manual override of totals: sets tax rate, shipping, and total amount, then calls calculate() to reparse totals according to override flags.

```php
// Manual override path: skip item math for totals
$invoice->taxRate(21)->shipping(4.5)->totalAmount(500.0);
$invoice->calculate(); // reparses totals per the override flags
```

--------------------------------

### Install Laravel Invoices via Composer

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/README.md

Install the Laravel Invoices package via Composer. Requires version ^4.1.1.

```bash
$ composer require laraveldaily/laravel-invoices:^4.1.1
```

--------------------------------

### Install laravel-invoices for Laravel <= 7

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/PREVIOUS.md

Install the package for Laravel versions 7 and below. Use this version constraint when your Laravel version is 7 or lower.

```bash
$ composer require laraveldaily/laravel-invoices:^1.3
```

--------------------------------

### Install laravel-invoices for Laravel <= 8

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/PREVIOUS.md

Install the package for Laravel versions 8 and below. Use this version constraint when your Laravel version is 8 or lower.

```bash
$ composer require laraveldaily/laravel-invoices:^2.0
```

--------------------------------

### Install laravel-invoices for Laravel <= 9

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/PREVIOUS.md

Install the package for Laravel versions 9 and below. Use this version constraint when your Laravel version is 9 or lower.

```bash
$ composer require laraveldaily/laravel-invoices:^3.3
```

--------------------------------

### Run tests with composer test

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/README.md

Runs the test suite for the laravel-invoices package. Use this command to verify the package works correctly after installation or during development.

```bash
$ composer test
```

--------------------------------

### Save invoice to local disk and get URL

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-formatters.md

Saves the invoice to the 'local' disk and returns the URL to the saved file. The url() method assumes the file was previously saved via save(); it does not render or write by itself.

```php
$invoice->save('local');
return $invoice->url(); // e.g. "http://host/storage/AA_00001.pdf"
```

--------------------------------

### Save invoice to public disk and get URL

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-formatters.md

Saves the invoice to the 'public' disk and then retrieves the public URL of the saved file. The save() method renders the invoice and writes the PDF bytes to the specified disk, overriding the default disk property.

```php
$invoice->filename('my-invoice')->save('public');
$link = $invoice->url(); // public URL of the saved file
```

--------------------------------

### Creating invoice items with discounts and taxes

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice-item.md

Shows how to create InvoiceItem instances with fluent methods for description, price per unit, quantity, discount, units, discount by percent, and tax by percent. The discount is an absolute currency amount, while discountByPercent and taxByPercent use percentages.

```php
use LaravelDaily\Invoices\Classes\InvoiceItem;

$items = [
    InvoiceItem::make('Service 1')
        ->description('Your product or service description')
        ->pricePerUnit(47.79)
        ->quantity(2)
        ->discount(10),                      // absolute discount in currency
    InvoiceItem::make('Service 4')
        ->pricePerUnit(87.51)
        ->quantity(7)
        ->discount(4)
        ->units('kg'),
    InvoiceItem::make('Service 5')
        ->pricePerUnit(71.09)
        ->quantity(7)
        ->discountByPercent(9)               // 9% discount
        ->taxByPercent(8),                   // 8% tax
];
```

--------------------------------

### Create invoice using Invoice facade

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/README.md

Alternative usage using the Invoice facade to create a party and an item, then build and stream an invoice.

```php
use Invoice;

$customer = Invoice::makeParty([
    'name' => 'John Doe',
]);

$item = Invoice::makeItem('Your service or product title')->pricePerUnit(9.99);

return Invoice::make()->buyer($customer)->addItem($item)->stream();
```

--------------------------------

### Create Party instance with attributes

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/types.md

Constructs a Party instance with a properties array. The name attribute is set, while email is not provided and reads as null.

```php
$party = new Party([
    'name'          => 'Roosevelt Lloyd',
    'phone'         => '(520) 318-9486',
    'custom_fields' => ['note' => 'IDDQD', 'business id' => '365#GG'],
]);
$party->name;  // 'Roosevelt Lloyd'
$party->email; // null
```

--------------------------------

### Invoice::__construct

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Creates a new Invoice instance, initializing all properties from configuration. Throws BindingResolutionException if the seller class cannot be resolved.

```APIDOC
## Invoice::__construct

### Description
Creates a new Invoice instance, initializing all properties from configuration. Throws BindingResolutionException if the seller class cannot be resolved.

### Method
Constructor

### Signature
`public function __construct($name = '')`

### Parameters
- `name` (string) - Optional - Default: `''` - Invoice title; falls back to the `invoices::invoice.invoice` translation when empty

### Throws
- `\Illuminate\Contracts\Container\BindingResolutionException` - if the container cannot resolve `config('invoices.seller.class')` via `app()->make()`.

### Behavior
Initializes: date = `Carbon::now()`; date format/pay-until-days, serial number series/sequence/padding/delimiter/format, currency code/fraction/symbol/decimals/point/thousands separator/format, paper options, DomPDF options and disk — all from `config('invoices.*')`. The series/sequence also (re)computes the default filename.

### Example
```php
use LaravelDaily\Invoices\Invoice;

$invoice = new Invoice('Custom title'); // same as Invoice::make('Custom title')
```
```

--------------------------------

### Create party with makeParty

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Creates a Party object with name and code attributes using the `makeParty` static factory.

```php
$buyer = Invoice::makeParty(['name' => 'Acme Inc.', 'code' => '12-345']);
```

--------------------------------

### Seller class with config-loaded attributes

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/party.md

Seller class implementing PartyContract. Constructor takes no parameters and loads every attribute from config('invoices.seller.attributes.*') at construction time. Attributes are fixed fields, not copied from a properties array.

```php
class Seller implements PartyContract
{
    /**
     * @var \Illuminate\Config\Repository|mixed
     */
    public $name;

    /**
     * @var \Illuminate\Config\Repository|mixed
     */
    public $address;

    /**
     * @var \Illuminate\Config\Repository|mixed
     */
    public $code;

    /**
     * @var \Illuminate\Config\Repository|mixed
     */
    public $vat;

    /**
     * @var \Illuminate\Config\Repository|mixed
     */
    public $phone;

    /**
     * @var \Illuminate\Config\Repository|mixed
     */
    public $custom_fields;

    /**
     * Seller constructor.
     */
    public function __construct()
    {
        $this->name          = config('invoices.seller.attributes.name');
        $this->address       = config('invoices.seller.attributes.address');
        $this->code          = config('invoices.seller.attributes.code');
        $this->vat           = config('invoices.seller.attributes.vat');
        $this->phone         = config('invoices.seller.attributes.phone');
        $this->custom_fields = config('invoices.seller.attributes.custom_fields');
    }
}
```

--------------------------------

### PricingService class with static rounding methods

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/pricing-service.md

Full source of the PricingService class with static methods applyDiscount, applyTax, and applyQuantity. All methods round to the given $decimals using round().

```php
class PricingService
{
    public static function applyDiscount(float $target, float $discount, int $decimals, bool $rate = false)
    {
        if ($rate) {
            return round($target * (1 - $discount / 100), $decimals);
        }

        return round($target - $discount, $decimals);
    }

    public static function applyTax(float $target, float $tax, int $decimals, bool $rate = false)
    {
        if ($rate) {
            return round($target * (1 + $tax / 100), $decimals);
        }

        return round($target + $tax, $decimals);
    }

    public static function applyQuantity(float $target, float $quantity, int $decimals)
    {
        return round($target * $quantity, $decimals);
    }
}
```

--------------------------------

### Compose an invoice with Invoice::make and addItem

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Creates a receipt invoice with a tax rate, shipping cost, and one item, then validates, calculates totals, and outputs the total amount in words. Requires buyer, seller, and items to be set before validation.

```php
use LaravelDaily\Invoices\Invoice;
use LaravelDaily\Invoices\Classes\InvoiceItem;

$invoice = Invoice::make('receipt')
    ->status(__('invoices::invoice.paid'))
    ->taxRate(15)
    ->shipping(1.99)
    ->addItem(InvoiceItem::make('Service 1')->pricePerUnit(2))
    ->setCustomData(['ref' => 'AB-1']);

$invoice->validate();  // throws unless buyer/seller/items are set
$invoice->calculate(); // fills total_discount/total_taxes/total_amount etc.
echo $invoice->getTotalAmountInWords();
```

--------------------------------

### Fluent invoice creation with make

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Chains `buyer()`, `addItem()`, and `stream()` on an Invoice created via `Invoice::make()`. Demonstrates a typical fluent workflow for generating and streaming an invoice.

```php
$invoice = Invoice::make()->buyer($customer)->addItem($item)->stream();
```

--------------------------------

### Seller constructor signature

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/party.md

Constructor signature for Seller. No parameters; all attributes are loaded from config at construction time.

```php
public function __construct()
```

--------------------------------

### InvoiceItem::__construct

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice-item.md

Initializes a new InvoiceItem instance with default values for quantity, discount, and tax.

```APIDOC
## InvoiceItem::__construct

### Description
Initializes a new InvoiceItem instance with default values: quantity = 1.0, discount = 0.0, tax = 0.0.

### Method
Constructor

### Signature
```php
public function __construct()
```

### Parameters
None.

### Returns
A new InvoiceItem instance.
```

--------------------------------

### download

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Downloads the PDF as an attachment. Calls render() first.

```APIDOC
## download

### Description
Downloads the PDF as an attachment. Calls render() first.

### Method
download

### Parameters
None

### Returns
Illuminate\Http\Response with status Response::HTTP_OK and headers:
- Content-Type: application/pdf
- Content-Disposition: attachment; filename="<this.filename>"
- Content-Length: strlen($this->output)

### Throws
Exception - same validation/calculation conditions as render().

### Example
```php
return $invoice->download(); // browser saves the PDF
```
```

--------------------------------

### InvoiceServiceProvider class skeleton

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/provider-and-commands.md

Shows the class structure of InvoiceServiceProvider with its public lifecycle hooks (boot, register, provides) and protected helper methods (registerResources, defineAssetPublishing, configure, offerPublishing, registerServices, registerCommands). The methods are shown without bodies; the behavior table describes what each method does.

```php
class InvoiceServiceProvider extends ServiceProvider
{
    /**
     * Perform post-registration booting of services.
     *
     * @return void
     */
    public function boot()

    /**
     * Register the Invoices routes.
     *
     * @return void
     */
    protected function registerResources()

    /**
     * Define the asset publishing configuration.
     *
     * @return void
     */
    protected function defineAssetPublishing()

    /**
     * Register any package services.
     *
     * @return void
     */
    public function register()

    /**
     * Setup the configuration for Invoices.
     *
     * @return void
     */
    protected function configure()

    /**
     * Setup the resource publishing groups for Invoices.
     *
     * @return void
     */
    protected function offerPublishing()

    /**
     * Register Invoices' services in the container.
     *
     * @return void
     */
    protected function registerServices()

    /**
     * Register the Invoices Artisan commands.
     *
     * @return void
     */
    protected function registerCommands()

    /**
     * Get the services provided by the provider.
     *
     * @return array
     */
    public function provides()
}
```

--------------------------------

### Typical usage: Create and stream an invoice

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Shows how to create a buyer, an invoice item, and an invoice with discount, tax, and shipping, then stream the invoice as a response. Uses the LaravelDaily\Invoices\Invoice, Buyer, and InvoiceItem classes.

```php
use LaravelDaily\Invoices\Invoice;
use LaravelDaily\Invoices\Classes\Buyer;
use LaravelDaily\Invoices\Classes\InvoiceItem;

$customer = new Buyer(['name' => 'John Doe', 'custom_fields' => ['email' => 'test@example.com']]);
$item     = InvoiceItem::make('Service 1')->pricePerUnit(2);

$invoice = Invoice::make()
    ->buyer($customer)
    ->discountByPercent(10)
    ->taxRate(15)
    ->shipping(1.99)
    ->addItem($item);

return $invoice->stream();
```

--------------------------------

### POST /api/users

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/party.md

Creates a new user in the system.

```APIDOC
## [POST] /api/users

### Description
Creates a new user in the system.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **name** (string) - Required - The user's full name
- **email** (string) - Required - The user's email address

### Request Example
{
  "name": "John Doe",
  "email": "john@example.com"
}

### Response
#### Success Response (201)
- **id** (integer) - The unique identifier of the created user
- **name** (string) - The user's full name
- **email** (string) - The user's email address

#### Response Example
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}
```

--------------------------------

### InvoiceItem constructor

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice-item.md

Initializes a new InvoiceItem with default values: quantity = 1.0, discount = 0.0, tax = 0.0. Takes no parameters.

```php
    /**
     * InvoiceItem constructor.
     */
    public function __construct()
```

--------------------------------

### calculate() method

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Called by beforeRender(). Returns $this. Iterates items, enforces exclusivity of taxes/discounts, calculates per-item totals, and applies overrides based on flags.

```php
    /**
     * @return $this
     */
    public function calculate()
```

--------------------------------

### PricingService::applyQuantity

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/pricing-service.md

Static method to calculate the total price for a given quantity, with rounding.

```APIDOC
## `applyQuantity`

### Description
Multiplies a target price per unit by a quantity and rounds the result to the specified number of decimals.

### Method
`PricingService::applyQuantity`

### Signature
```php
public static function applyQuantity(float $target, float $quantity, int $decimals)
```

### Parameters
- **target** (float) - Required - Price per unit
- **quantity** (float) - Required - Unit count (may be fractional)
- **decimals** (int) - Required - Rounding precision

### Returns
float - `round(target * quantity, decimals)`.

### Example
```php
PricingService::applyQuantity(25.55, 0.5, 2); // 12.78
```
```

--------------------------------

### notes

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Sets multiline notes; rendered with {!! .. !!} so HTML such as <br> is allowed.

```APIDOC
## notes

### Description
Sets multiline notes; rendered with {!! .. !!} so HTML such as <br> is allowed.

### Method
Fluent setter

### Signature
`public function notes(string $notes)`

### Parameters
- `notes` (string) - Required - The multiline notes.

### Returns
`$this`
```

--------------------------------

### Instantiate Invoice with constructor

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Creates a new Invoice instance with a custom title using the constructor. Equivalent to calling `Invoice::make('Custom title')`.

```php
use LaravelDaily\Invoices\Invoice;

$invoice = new Invoice('Custom title'); // same as Invoice::make('Custom title')
```

--------------------------------

### Create item with makeItem

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Creates an InvoiceItem with title 'Consulting', price per unit 120, and quantity 8 using the `makeItem` static factory and fluent setters.

```php
$item = Invoice::makeItem('Consulting')->pricePerUnit(120)->quantity(8);
```

--------------------------------

### Format currency with custom symbol and format

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-formatters.md

Sets the currency symbol and format, then formats a float amount. The output is "$1.99".

```php
$invoice->currencySymbol('$')->currencyFormat('{SYMBOL}{VALUE}');
$invoice->formatCurrency(1.99); // "$1.99"
```

--------------------------------

### filename

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Sets the filename, appending '.pdf' to the given string.

```APIDOC
## filename

### Description
Sets the filename, appending '.pdf' to the given string.

### Method
Fluent setter

### Signature
`public function filename(string $filename)`

### Parameters
- `filename` (string) - Required - The base filename.

### Returns
`$this`
```

--------------------------------

### PricingService::applyDiscount

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/pricing-service.md

Static method to apply a discount to a target amount, either as an absolute subtraction or as a percentage rate, with rounding.

```APIDOC
## `applyDiscount`

### Description
Applies a discount to a target amount, either as an absolute subtraction or as a percentage rate, and rounds the result to the specified number of decimals.

### Method
`PricingService::applyDiscount`

### Signature
```php
public static function applyDiscount(float $target, float $discount, int $decimals, bool $rate = false)
```

### Parameters
- **target** (float) - Required - Base amount to apply the discount to
- **discount** (float) - Required - Absolute amount to subtract, or percentage rate when `rate=true`
- **decimals** (int) - Required - Rounding precision
- **rate** (bool) - Optional (default `false`) - `true` → multiplicative percentage: `round(target * (1 - discount/100), decimals)`; `false` → subtractive: `round(target - discount, decimals)`

### Returns
float - Discounted amount rounded to `$decimals`.

### Example
```php
PricingService::applyDiscount(49.99, 9.555, 2);        // 40.44
PricingService::applyDiscount(49.99, 15.666, 2, true); // 42.16
```
```

--------------------------------

### Import Invoice class

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Import statement for the Invoice class.

```php
use LaravelDaily\Invoices\Invoice;
```

--------------------------------

### Class Buyer

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/types.md

Documentation for the Buyer class, an empty subclass of Party.

```APIDOC
## Class `Buyer extends Party`

### Description
Empty subclass of `Party`; inherits all dynamic behavior. Same constructor contract as `Party` (must pass the `$properties` array). Accepted by the same `PartyContract` slots as `Party`.

### Import
`use LaravelDaily\Invoices\Classes\Buyer;`

### Source
`src/Classes/Buyer.php`

### Constructor
- **$properties** (array) - Required - Properties to initialize the buyer.
```

--------------------------------

### Invoice::make

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Static factory method that returns a new Invoice instance. Throws BindingResolutionException if the seller class cannot be resolved.

```APIDOC
## Invoice::make

### Description
Static factory method that returns a new Invoice instance. Throws BindingResolutionException if the seller class cannot be resolved.

### Method
Static Factory

### Signature
`public static function make($name = '')`

### Parameters
- `name` (string) - Optional - Default: `''` - Invoice title (falls back to localized `"Invoice"`)

### Returns
- `Invoice` - A new Invoice instance (`new static($name)`).

### Example
```php
$invoice = Invoice::make()->buyer($customer)->addItem($item)->stream();
```
```

--------------------------------

### UpdateCommand: invoices:update signature and handle()

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/provider-and-commands.md

Defines the invoices:update command signature, description, and handle() method. When run, it warns 'This will overwrite default templates and translations.', asks for confirmation, and if confirmed publishes the invoices.views and invoices.translations tags with --force, then prints 'Invoices Views and Translations updated successfully.' If declined, nothing is published.

```php
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'invoices:update';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Update Invoices Views and Translations';

    /**
     * Execute the console command.
     *
     * @return void
     */
    public function handle()
```

```bash
$ php artisan invoices:update
```

--------------------------------

### render

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Renders the invoice to PDF. Renders only once; if the PDF is already set, it returns early. Runs validation and calculation before rendering.

```APIDOC
## render

### Description
Renders the invoice to PDF. Renders only once; if the PDF is already set, it returns early. Runs validation and calculation before rendering.

### Method
render

### Parameters
None

### Returns
`$this`

### Throws
`Exception` - rethrown from validate()/calculate(), e.g. 'Buyer not defined.', 'No items to invoice defined.', or tax/discount exclusivity violations.

### Example
```php
$invoice->render(); // $invoice->pdf and $invoice->output are now populated
```
```

--------------------------------

### totalDiscount(float $total_discount, bool $byPercent = false)

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Sets the total discount amount or rate for the invoice. Throws an exception if a discount is already set.

```APIDOC
## totalDiscount(float $total_discount, bool $byPercent = false)

### Description
Sets the total discount amount or rate for the invoice. Throws an exception if a discount is already set.

### Method
totalDiscount

### Signature
`public function totalDiscount(float $total_discount, bool $byPercent = false)`

### Parameters
- `total_discount` (float) - Required - Total discount amount, or rate percent when `byPercent=true`.
- `byPercent` (bool) - Optional - Default: `false`. When `true`, `amount` is also stored as `$this->discount_percentage`.

### Returns
`$this`

### Throws
`Exception` - 'Invoice: unable to set discount twice.' when `hasDiscount()` is already true.
```

--------------------------------

### Custom Party class implementing PartyContract

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/party.md

Defines a custom Company class implementing PartyContract and shows how to create seller and buyer parties, then assign them to an invoice.

```php
use LaravelDaily\Invoices\Classes\Party;
use LaravelDaily\Invoices\Contracts\PartyContract;

class Company implements PartyContract
{
    public function __construct(public $name, public $vat, public $custom_fields = []) {}
}

$seller = new Seller(); // prefilled from config('invoices.seller.attributes.*')
$buyer  = new Party([
    'name'          => 'Roosevelt Lloyd',
    'phone'         => '(520) 318-9486',
    'custom_fields' => ['note' => 'IDDQD', 'business id' => '365#GG'],
]);

$invoice->seller($seller)->buyer($buyer);
```

--------------------------------

### Party class with dynamic properties

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/party.md

The Party class implements PartyContract. Its constructor copies all properties from the input array onto the instance, and __get returns null for missing attributes.

```php
/**
 * Class Party
 */
#[
AllowDynamicProperties]
class Party implements PartyContract
{
    public $custom_fields;

    /**
     * Party constructor.
     * @param $properties
     */
    public function __construct($properties)
    {
        $this->custom_fields = [];

        foreach ($properties as $property => $value) {
            $this->{$property} = $value;
        }
    }

    /**
     * @param $key
     * @return mixed|null
     */
    public function __get($key)
    {
        return $this->{$key} ?? null;
    }
}
```

--------------------------------

### Invoice constructor

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Constructor signature for the Invoice class. Accepts an optional invoice title; when empty, falls back to the `invoices::invoice.invoice` translation. Throws `BindingResolutionException` if the container cannot resolve `config('invoices.seller.class')` via `app()->make()`. Initializes date, format, serial number, currency, paper, DomPDF, and disk options from `config('invoices.*')`.

```php
    /**
     * Invoice constructor.
     *
     * @param string $name
     *
     * @throws \Illuminate\Contracts\Container\BindingResolutionException
     */
    public function __construct($name = '')
```

--------------------------------

### Buyer class extends Party

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/types.md

Empty subclass of Party; inherits all dynamic behavior. Same constructor contract as Party (must pass the $properties array). Accepted by the same PartyContract slots as Party.

```php
class Buyer extends Party
{
}
```

--------------------------------

### download method signature

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Signature of the download method. It calls render() first and returns a Response with Content-Type application/pdf, attachment Content-Disposition, and Content-Length header. Throws Exception on validation/calculation errors.

```php
    /**
     * @throws Exception
     *
     * @return Response
     */
    public function download()
```

--------------------------------

### discountByPercent(float $discount)

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Sets the discount percentage for the invoice. Equivalent to totalDiscount($discount, true).

```APIDOC
## discountByPercent(float $discount)

### Description
Sets the discount percentage for the invoice. Equivalent to totalDiscount($discount, true).

### Method
discountByPercent

### Signature
`public function discountByPercent(float $discount)`

### Parameters
- `discount` (float) - Required - Discount percentage (10 means 10%).

### Returns
`$this`

### Throws
`Exception` - 'Invoice: unable to set discount twice.' when `hasDiscount()` is already true.
```

--------------------------------

### PricingService::applyTax

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/pricing-service.md

Static method to apply a tax to a target amount, either as an absolute addition or as a percentage rate, with rounding.

```APIDOC
## `applyTax`

### Description
Applies a tax to a target amount, either as an absolute addition or as a percentage rate, and rounds the result to the specified number of decimals.

### Method
`PricingService::applyTax`

### Signature
```php
public static function applyTax(float $target, float $tax, int $decimals, bool $rate = false)
```

### Parameters
- **target** (float) - Required - Base amount to apply the tax to
- **tax** (float) - Required - Absolute amount to add, or percentage rate when `rate=true`
- **decimals** (int) - Required - Rounding precision
- **rate** (bool) - Optional (default `false`) - `true` → multiplicative percentage: `round(target * (1 + tax/100), decimals)`; `false` → additive: `round(target + tax, decimals)`

### Returns
float - Amount including tax, rounded to `$decimals`.

### Example
```php
PricingService::applyTax(49.99856, 10.11111, 2);    // 60.11
PricingService::applyTax(49.99, 21, 2, true);       // 60.49
```
```

--------------------------------

### Spell out amount in words with currency settings

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-formatters.md

Configures currency code, fraction, and decimals, then spells out an amount in words. The output is "Eight hundred fifty thousand sixty-eight EUR and fifteen ct.".

```php
$invoice->currencyCode('EUR')->currencyFraction('ct.')->currencyDecimals(2);
$invoice->getAmountInWords(850068.15, 'en'); // "Eight hundred fifty thousand sixty-eight EUR and fifteen ct."
```

--------------------------------

### Handle invoice streaming exceptions

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Wraps $invoice->stream() in a try-catch to report exceptions such as 'Buyer not defined.' or 'Seller not defined.'. Use this pattern to gracefully handle invoice generation errors.

```php
try {
    $invoice->stream();
} catch (\Exception $e) {
    // Any of: 'Buyer not defined.', 'Seller not defined.',
    // 'No items to invoice defined.', 'Invoice: unable to set (tax|discount) twice.',
    // 'Invoice: you must have taxes only on items or only on invoice.',
    // 'Invoice: you must have discounts only on items or only on invoice.'
    report($e->getMessage());
}
```

--------------------------------

### Dynamic access fallback for Party

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/party.md

Shows that accessing an undefined property on a Party instance returns null via __get, avoiding errors.

```php
$buyer = new Party(['name' => 'Acme']);
$buyer->unknown; // null (via __get), no error
```

--------------------------------

### logo

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/traits-invoice-helpers.md

Sets the path to a logo image (used by getLogo()).

```APIDOC
## logo

### Description
Sets the path to a logo image (used by getLogo()).

### Method
Fluent setter

### Signature
`public function logo(string $logo)`

### Parameters
- `logo` (string) - Required - Path to a logo image.

### Returns
`$this`
```

--------------------------------

### Party constructor signature

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/party.md

Constructor signature for the Party class. Accepts an associative array of attribute name => value pairs.

```php
    public function __construct($properties)
```

--------------------------------

### InvoiceItem class with public properties

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/types.md

Invoice item with fields for title, description, units, quantity, price, subtotal, discount, and tax. Returned by InvoiceItem::make($title), Invoice::makeItem(), and the Invoice facade. Accepted by Invoice::addItem() and Invoice::addItems().

```php
class InvoiceItem
{
    public $title;              // string|null
    public $description = false; // string|bool
    public $units;              // string|null
    public $quantity;           // float (1.0 default)
    public $price_per_unit;     // float|null
    public $sub_total_price;    // float|null
    public $discount;           // float (0.0 default)
    public $discount_percentage;// bool|null
    public $tax;                // float (0.0 default)
    public $tax_percentage;     // float|null
}
```

--------------------------------

### Import InvoiceServiceProvider

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/provider-and-commands.md

Import the InvoiceServiceProvider class. The provider is auto-discovered, but manual registration in config/app.php is possible for Laravel versions before 5.5.

```php
use LaravelDaily\Invoices\InvoiceServiceProvider;
```

--------------------------------

### render method signature

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/_autodocs/api-reference/invoice.md

Signature of the render method. It renders the invoice to PDF, running validation and calculation, and populates $this->pdf and $this->output. Throws Exception on validation/calculation errors.

```php
    /**
     * @throws Exception
     *
     * @return $this
     */
    public function render()
```

--------------------------------

### Publish Laravel Invoices views separately

Source: https://github.com/laraveldaily/laravel-invoices/blob/master/README.md

Publish only the invoice views, forcing the override of existing files.

```bash
$ php artisan vendor:publish --tag=invoices.views --force
```
Tokens:
Raw