Laravel Invoices Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   This publishes assets, views, translations, and config.

2. First Use Case: Generate a basic invoice with a single item:

   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(10.99))
       ->stream();
   

Key Starting Points

• Config: config/invoices.php (overrides defaults like currency, serial numbers, seller details).
• Templates: resources/views/vendor/invoices/templates/default.blade.php (customize invoice layout).
• Facade: Invoice::make() for quick instantiation (alternative to class instantiation).

Implementation Patterns

Core Workflow

1. Define Parties:

   $seller = Invoice::makeParty(['name' => 'Your Company']);
   $buyer = Invoice::makeParty(['name' => 'Client', 'email' => 'client@example.com']);
   

2. Create Items:

   $item = InvoiceItem::make('Consulting')
       ->pricePerUnit(150)
       ->quantity(2)
       ->taxByPercent(10);
   

3. Build Invoice:

   $invoice = Invoice::make()
       ->seller($seller)
       ->buyer($buyer)
       ->addItems([$item, $item2])
       ->taxRate(5)
       ->discountByPercent(5)
       ->save('public'); // Save to disk
   

4. Deliver Invoice:

   return $invoice->stream(); // Open in browser
   // OR
   return $invoice->download(); // Force download
   

Common Patterns

• Dynamic Overrides: Override config values per invoice (e.g., currencySymbol('$')).
• Custom Templates: Use template('custom') to switch layouts.
• Localization: Pass locale to getAmountInWords() for currency spelling (e.g., getAmountInWords(100, 'es')).
• Batch Processing: Loop through orders and generate invoices:

  foreach ($orders as $order) {
      $invoice = Invoice::make()
          ->buyer($order->customer)
          ->addItems($order->items)
          ->save('public');
      // Send email with $invoice->url()
  }
  

Integration Tips

• Storage: Use save($disk) to store invoices in S3, local, etc. Retrieve with url().
• Email Attachments: Attach PDFs to emails using Storage::disk('public')->get($invoice->filename).
• Webhooks: Trigger invoice generation post-order creation (e.g., Laravel Events).
• API Responses: Return invoice URLs or base64-encoded PDFs:

  return response()->json(['invoice_url' => $invoice->url()]);
  

Gotchas and Tips

Pitfalls

1. Template Paths:

   • Custom templates must be in resources/views/vendor/invoices/templates/.
   • Forgetting to run php artisan invoices:update after updates may break templates.

2. Serial Number Conflicts:

   • Default sequence_padding (5) may cause gaps if sequences aren’t sequential. Adjust or use a database-backed sequence.

3. Currency Formatting:

   • currencyFormat uses tags {VALUE}, {SYMBOL}, {CODE}. Misplaced tags (e.g., {SYMBOL}{VALUE} vs {VALUE} {SYMBOL}) can break alignment.

4. Logo Issues:

   • Paths in logo() must be absolute (e.g., public_path('images/logo.png')). Use getLogo() in templates to avoid path problems.

5. Tax/Discount Calculations:

   • If manually setting totalTaxes() or totalDiscount(), ensure they match calculated values to avoid discrepancies.

Debugging Tips

• Inspect Generated HTML: Use toHtml() to debug template rendering before PDF generation.
• Check Config Overrides: Verify dynamic overrides (e.g., currencySymbol()) take precedence over config.
• Log Serial Numbers: Add dd($invoice->getSerialNumber()) to debug formatting issues.
• Test Locally: Use php artisan invoices:update to reset templates if changes aren’t reflecting.

Extension Points

1. Custom Party Classes: Extend LaravelDaily\Invoices\Classes\Party to add fields (e.g., taxId):

   class CustomBuyer extends Party {
       public function taxId() { return $this->custom_fields['tax_id'] ?? null; }
   }
   

   Update config:

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

2. Dynamic Templates: Use Blade directives to conditionally render sections:

   @if($invoice->getCustomData('is_recurring'))
       <div>Recurring Invoice</div>
   @endif
   

3. Hooks: Override methods like getTotalAmount() to add custom logic (e.g., loyalty discounts):

   $invoice->setCustomData(['loyalty_discount' => 10]);
   // In a custom class:
   public function getTotalAmount() {
       $baseTotal = parent::getTotalAmount();
       return $baseTotal - ($baseTotal * ($this->getCustomData('loyalty_discount') ?? 0) / 100);
   }
   

4. Localization: Add translations for custom fields in resources/lang/{locale}/invoices.php:

   return [
       'custom_fields' => [
           'tax_id' => 'Tax ID',
       ],
   ];
   

Performance Notes

• Avoid stream() in Loops: Generate PDFs in bulk, then stream/download.
• Cache Templates: For high-volume invoices, cache compiled Blade templates.
• Use Queues: Offload invoice generation to queues for long-running processes.