Laravel Invoices Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require elegantly/laravel-invoices
   php artisan vendor:publish --tag="invoices-migrations"
   php artisan migrate
   

   For config publishing (optional but recommended):

   php artisan vendor:publish --tag="invoices-config"
   

2. First Use Case: Generate a simple PDF invoice without database storage:

   use Elegantly\Invoices\Pdf\PdfInvoice;
   use Elegantly\Invoices\Support\{Seller, Buyer, Address};
   
   $pdf = new PdfInvoice(
       name: "Test Invoice",
       serial_number: "INV-001",
       seller: new Seller(
           company: "Your Company",
           address: new Address(city: "New York")
       ),
       buyer: new Buyer(name: "John Doe"),
       items: [/* items array */]
   );
   
   return $pdf->stream();
   

Where to Look First

• PDF Generation: PdfInvoice class in Pdf/ namespace
• Database Model: Invoice Eloquent model in Models/ namespace
• Configuration: Published config file (config/invoices.php)
• Templates: Default Blade templates in resources/views/vendor/invoices/

Implementation Patterns

Core Workflows

1. Database + PDF Workflow

// Create invoice via model
$invoice = Invoice::create([
    'serial_number' => 'INV-001',
    'seller_id' => auth()->id(),
    'buyer_name' => 'Client Co.',
    // ...
]);

// Generate PDF from model
return $invoice->pdf()->download();

2. Standalone PDF Generation

// For non-database invoices (e.g., admin previews)
$pdf = new PdfInvoice(/* params */);
return $pdf->stream();

3. Livewire Integration

// In Livewire component
public function downloadPdf()
{
    $pdf = new PdfInvoice(/* params */);
    return $pdf->download();
}

4. Email Attachments

// In Mailable
public function build()
{
    $invoice = Invoice::find(1);
    return $this->attachData(
        $invoice->pdf()->getPdfOutput(),
        $invoice->getFilename()
    );
}

Integration Tips

With Livewire:

// Livewire component
public function render()
{
    $pdf = new PdfInvoice(/* params */);
    return view('livewire.invoice-view', [
        'pdfPreview' => $pdf->getHtml()
    ]);
}

With Queues:

// Dispatch PDF generation job
GenerateInvoicePdf::dispatch($invoiceId);

// Job class
public function handle()
{
    $invoice = Invoice::find($this->invoiceId);
    Storage::put(
        "invoices/{$invoice->getFilename()}",
        $invoice->pdf()->getPdfOutput()
    );
}

Custom Templates:

1. Publish views:

   php artisan vendor:publish --tag="invoices-views"
   

2. Override default.layout in resources/views/vendor/invoices/

Gotchas and Tips

Common Pitfalls

1. PDF Generation Failures:

   • Issue: Blank PDFs or missing assets
   • Fix: Ensure isRemoteEnabled: true in config and verify:

     'options' => [
         'isRemoteEnabled' => true,
         'fontDir' => storage_path('app/dompdf'),
         'fontCache' => storage_path('app/dompdf'),
     ]
     

2. Serial Number Conflicts:

   • Issue: Duplicate serial numbers when auto_generate: true
   • Fix: Configure multiple series in config:

     'serial_number' => [
         'format' => 'PPSSSS-YYCCCC',
         'prefix' => [
             InvoiceType::Invoice->value => 'INV',
             InvoiceType::Quote->value => 'QOT',
         ],
     ]
     

3. Money Calculation Errors:

   • Issue: Incorrect totals due to rounding
   • Fix: Set rounding mode in config:

     'rounding_mode' => RoundingMode::HalfUp,
     

Debugging Tips

• Template Issues: Use dd($pdf->getHtml()) to inspect raw HTML before PDF conversion.

• Storage Paths: Verify storage_path() permissions and Dompdf cache paths.

• Enum Casting: Ensure state and type are properly cast in your Invoice model:

  protected $casts = [
      'state' => InvoiceState::class,
      'type' => InvoiceType::class,
  ];
  

Extension Points

1. Custom PDF Classes: Extend PdfInvoice for reusable configurations:

   class CustomPdfInvoice extends PdfInvoice
   {
       public function __construct()
       {
           parent::__construct(/* default params */);
           $this->templateData['color'] = '#2c3e50';
       }
   }
   

2. Dynamic Logo Handling: Override logo logic in Invoice model:

   public function getLogoAttribute()
   {
       return $this->seller->company === 'Premium'
           ? 'premium-logo.png'
           : 'default-logo.png';
   }
   

3. Event Listeners: Hook into invoice events (e.g., InvoiceCreated):

   Invoice::created(function ($invoice) {
       // Send notification or log
   });
   

Configuration Quirks

• Google Fonts: Add URLs to template_data.fonts and ensure fontDir is writable:

  'fonts' => [
      'https://fonts.googleapis.com/css2?family=Roboto:wght@300;400&display=swap',
  ],
  

• Multi-Currency: Use elegantly/laravel-money for dynamic currency handling:

  use Brick\Money\Money;
  $item->unit_price = Money::of(99.99, $invoice->currency);
  

• Localization: Override Blade templates for language-specific content:

  // In your template
  @php echo __('invoices.payment_due', ['date' => $invoice->due_at]); @endphp