Laravel Invoices Laravel Package

Getting Started

Minimal Steps

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 simple invoice in a controller:

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

Where to Look First

• Config: config/invoices.php – Global settings for serial numbers, currency, seller details, etc.
• Templates: resources/views/vendor/invoices/templates/ – Customize invoice layouts.
• Facade: Invoice::make() – Quick access to core functionality without manual imports.

Implementation Patterns

Core Workflow

1. Define Parties:

   $seller = Invoice::makeParty(['name' => 'Your Company']);
   $buyer = Invoice::makeParty(['name' => 'Client']);
   

2. Create Items:

   $item = Invoice::makeItem('Product')
       ->pricePerUnit(50)
       ->quantity(2)
       ->taxByPercent(10);
   

3. Build Invoice:

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

4. Output:

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

Integration Tips

• Dynamic Data: Attach custom data to invoices for templates:

  $invoice->setCustomData(['project_id' => 123]);
  

  Access in template via $invoice->customData.

• Localization: Override translations in resources/lang/vendor/invoices/. Use getAmountInWords() with locales:

  $invoice->getTotalAmountInWords('es'); // Spanish
  

• Templates: Extend default.blade.php or create new templates in resources/views/vendor/invoices/templates/. Specify template:

  $invoice->template('custom_template');
  

• Automation: Use Invoice::make() facade in queues/jobs for batch invoice generation:

  Invoice::make()->buyer($client)->addItem($item)->save('s3');
  

• Validation: Validate Buyer/Seller data before passing to Invoice::make():

  $buyer = new Buyer(['name' => 'Client', 'email' => 'client@example.com']);
  if (!$buyer->isValid()) { /* Handle errors */ }
  

Gotchas and Tips

Pitfalls

1. Template Paths:

   • Forgetting to publish views (php artisan invoices:install) breaks custom templates.
   • Fix: Run php artisan vendor:publish --tag=invoices.views --force if missing.

2. Serial Number Conflicts:

   • Auto-incrementing sequences may clash if not configured properly.
   • Fix: Set sequence_padding in config or manually override:

     $invoice->sequence(1000)->sequencePadding(6);
     

3. Currency Formatting:

   • Incorrect currencyFormat or decimal_point can break PDF rendering.
   • Fix: Test with formatCurrency(1234.56) before generating invoices.

4. Logo Paths:

   • Hardcoded paths in logo() fail in production.
   • Fix: Use absolute paths or storage_path():

     $invoice->logo(storage_path('app/public/logo.png'));
     

5. Disk Permissions:

   • save() fails silently if the disk lacks write permissions.
   • Fix: Verify config('invoices.disk') and permissions:

     chmod -R 755 storage/app/public
     

Debugging

• Check Generated HTML: Use toHtml() to debug template rendering:

  $html = $invoice->toHtml();
  // Inspect $html for issues
  

• Log Serial Numbers: Add logging for sequence generation:

  \Log::info('Invoice Serial:', ['serial' => $invoice->getSerialNumber()]);
  

• Validate Data: Use dd($invoice->getCustomData()) to inspect attached data in templates.

Extension Points

1. Custom Party Classes: Extend Party or implement PartyContract for custom logic:

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

2. Hooks: Override methods like getTotalAmount() in a custom invoice class:

   class CustomInvoice extends Invoice {
       public function getTotalAmount() {
           return parent::getTotalAmount() * 1.1; // Add 10% fee
       }
   }
   

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

   @if($invoice->hasShipping())
       <tr><td>Shipping</td><td>{{ $invoice->shipping }}</td></tr>
   @endif
   

4. Event Listeners: Listen for invoice generation events (if using Laravel events):

   Invoice::created(function ($invoice) {
       \Log::info('Invoice created:', $invoice->getSerialNumber());
   });
   

Pro Tips

• Batch Processing: Use Laravel queues to generate invoices asynchronously:

  Invoice::dispatch($invoiceData)->onQueue('invoices');
  

• Multi-Currency: Store currency settings per invoice:

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

• PDF Customization: Use dompdf options via config:

  config(['invoices.pdf_options' => ['defaultFont' => 'DejaVu Sans']]);
  

• Testing: Mock Invoice in tests:

  $invoice = Mockery::mock(Invoice::class);
  $invoice->shouldReceive('stream')->andReturn('pdf-content');