Laravel Invoices Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laraveldaily/laravel-invoices:^4.1.1
   php artisan invoices:install
   

   This publishes views, translations, and config to your project.

2. First Invoice:

   use LaravelDaily\Invoices\Invoice;
   use LaravelDaily\Invoices\Classes\Buyer;
   use LaravelDaily\Invoices\Classes\InvoiceItem;
   
   $invoice = Invoice::make()
       ->buyer(new Buyer(['name' => 'John Doe']))
       ->addItem(InvoiceItem::make('Service')->pricePerUnit(100))
       ->stream();
   

   • Output: Automatically streams a PDF invoice to the browser.

3. Key Directories:

   • Templates: resources/views/vendor/invoices/templates/
   • Config: config/invoices.php
   • Translations: resources/lang/vendor/invoices/

Implementation Patterns

Core Workflow

1. Invoice Creation:

   Invoice::make('receipt') // Optional type (e.g., 'receipt', 'proforma')
       ->seller($sellerParty)
       ->buyer($buyerParty)
       ->addItems($items)
       ->taxRate(15)
       ->discountByPercent(10);
   

2. Dynamic Overrides: Use method chaining to override config values per invoice:

   ->dateFormat('m/d/Y')
   ->currencySymbol('$')
   ->serialNumberFormat('{SERIES}-{SEQUENCE}')
   

3. File Handling:

   // Stream to browser
   $invoice->stream();
   
   // Download
   $invoice->download();
   
   // Save to disk (e.g., 'public')
   $invoice->save('public');
   
   // Get URL (if saved)
   $invoice->url();
   

4. Custom Data: Attach arbitrary data to invoices for template use:

   $invoice->setCustomData(['project_id' => 123]);
   // Access in template via `$invoice->customData`
   

Integration Tips

1. With Eloquent Models:

   // Attach invoice data to a model
   $order->invoice = $invoice->toHtml(); // Store HTML or PDF path
   $order->save();
   

2. Email Integration:

   Mail::to($buyer->email)->send(new InvoiceMail($invoice));
   

3. Batch Processing:

   foreach ($orders as $order) {
       $invoice = Invoice::make()
           ->buyer($order->customer)
           ->addItems($order->items)
           ->save('invoices');
       // Queue email or notification
   }
   

4. Template Customization: Extend the default template (default.blade.php) by copying it to resources/views/vendor/invoices/templates/your_template.blade.php and referencing it:

   Invoice::make()->template('your_template');
   

Gotchas and Tips

Pitfalls

1. Logo Paths:

   • Use absolute paths (e.g., public_path('images/logo.png')) or base64 encoding:

     $invoice->logo(base64_encode(file_get_contents('logo.png')));
     

2. Currency Formatting:

   • Ensure currencyDecimalPoint and currencyThousandsSeparator match your locale (e.g., , vs . for decimals).

3. Serial Number Conflicts:

   • If using a database-backed sequence, manually increment the sequence in config or via:

     $invoice->sequence($nextSequence);
     

4. Template Caching:

   • Clear Blade cache (php artisan view:clear) after modifying templates.

5. Locale-Specific Issues:

   • Translations are locale-aware. Ensure your app’s locale is set (e.g., config/app.php) or override dynamically:

     $invoice->getAmountInWords($total, 'es_ES'); // Spanish
     

Debugging Tips

1. Inspect Invoice Data:

   dd($invoice->toArray()); // Dump raw invoice data
   

2. Check Template Rendering: Use toHtml() to preview the template before PDF generation:

   return $invoice->toHtml();
   

3. Log Errors: Wrap invoice generation in a try-catch:

   try {
       $invoice->stream();
   } catch (\Exception $e) {
       Log::error('Invoice generation failed: ' . $e->getMessage());
   }
   

Extension Points

1. Custom Party Classes: Extend LaravelDaily\Invoices\Classes\Party to add fields:

   class CustomBuyer extends Party {
       public function getVatNumber() { ... }
   }
   

   Update config:

   'buyer' => [
       'class' => \App\CustomBuyer::class,
   ]
   

2. Dynamic Serial Numbers: Override getSerialNumber() in a custom invoice class:

   class CustomInvoice extends Invoice {
       public function getSerialNumber() {
           return 'CUST-' . $this->sequence;
       }
   }
   

3. Hooks for Post-Generation: Use events (e.g., invoice.saved) via Laravel’s event system to trigger actions after saving:

   event(new InvoiceSaved($invoice));
   

4. Multi-Currency Support: Dynamically set currency per invoice:

   $invoice->currencyCode('EUR')->currencySymbol('€');
   

Pro Tips

• Use Facades for Conciseness:

  Invoice::makeParty(['name' => 'Client'])
      ->addItem(Invoice::makeItem('Service')->pricePerUnit(50))
      ->stream();
  

• Leverage setCustomData for Metadata:

  $invoice->setCustomData([
      'terms' => 'Net 30',
      'reference' => $order->reference,
  ]);
  

• Batch Generate Invoices:

  $invoices = collect($orders)->map(function ($order) {
      return Invoice::make()
          ->buyer($order->customer)
          ->addItems($order->items)
          ->save('invoices');
  });