Filament Invoices Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tomatophp/filament-invoices
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="TomatoPHP\FilamentInvoices\FilamentInvoicesServiceProvider" --tag="filament-invoices-config"
   php artisan vendor:publish --provider="TomatoPHP\FilamentInvoices\FilamentInvoicesServiceProvider" --tag="filament-invoices-assets"
   

2. Run Migrations

   php artisan migrate
   

3. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \TomatoPHP\FilamentInvoices\FilamentInvoicesPlugin::make(),
           ]);
   }
   

4. First Use Case

   • Navigate to the Invoices section in Filament.
   • Click Create Invoice to generate a basic invoice using the default template.
   • Customize fields (client, items, currency, etc.) and save.

Where to Look First

• Config File: config/filament-invoices.php (currency settings, default templates, email configurations).
• Templates: resources/views/vendor/filament-invoices/ (customize or extend built-in templates).
• Facade: \TomatoPHP\FilamentInvoices\Facades\FilamentInvoices (for programmatic invoice generation).
• Widgets: Pre-built widgets for invoice stats (e.g., InvoiceStatsWidget) can be added to Filament dashboards.

Implementation Patterns

Core Workflows

1. Generating Invoices Programmatically

Use the facade to create invoices dynamically (e.g., after an order is placed):

use TomatoPHP\FilamentInvoices\Facades\FilamentInvoices;

$invoice = FilamentInvoices::create([
    'client_id' => $customer->id,
    'currency' => 'USD',
    'items' => [
        ['name' => 'Product A', 'quantity' => 2, 'unit_price' => 10.00],
    ],
    'template' => 'modern', // Uses built-in templates
]);

2. Morph Relationships

Attach invoices to any model using morphTo/morphWith:

// In your model (e.g., Order.php)
public function invoice()
{
    return $this->morphOne(Invoice::class, 'invoiceable');
}

// Generate invoice for an order
$order->invoice()->create([...]);

3. Handling Payments

Link payments to invoices and track statuses:

$invoice->payments()->create([
    'amount' => 50.00,
    'method' => 'credit_card',
    'status' => 'completed',
]);

4. Email Integration

Send invoices via email with PDF attachments:

$invoice->sendEmail([
    'to' => $client->email,
    'subject' => 'Your Invoice #'.$invoice->number,
]);

Integration Tips

Filament Dashboard Widgets

Add invoice stats to your Filament dashboard:

use TomatoPHP\FilamentInvoices\Widgets\InvoiceStatsWidget;

public function getWidgets(): array
{
    return [
        InvoiceStatsWidget::class,
    ];
}

Custom Templates

Extend the factory pattern to add new templates:

1. Create a new Blade template in resources/views/vendor/filament-invoices/templates/.
2. Register it in the config:

   'templates' => [
       'custom' => 'filament-invoices::templates.custom',
   ],
   

Status Management

Customize invoice statuses via the statuses config array:

'statuses' => [
    'draft' => ['label' => 'Draft', 'color' => 'gray'],
    'sent' => ['label' => 'Sent', 'color' => 'blue'],
    'paid' => ['label' => 'Paid', 'color' => 'green'],
],

Multi-Currency Support

Set default currency and exchange rates in config/filament-invoices.php:

'currency' => [
    'default' => 'USD',
    'rates' => [
        'EUR' => 0.85,
        'GBP' => 0.75,
    ],
],

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If you’ve manually created invoices or invoice_items tables, drop them before running migrations to avoid conflicts.

2. Template Overrides

   • Ensure custom templates extend the base layout (@extends('filament-invoices::layouts.invoice')) or they may break PDF generation.

3. DomPDF Dependencies

   • If PDF generation fails, verify dompdf/dompdf is installed and configured. Run:

     composer require dompdf/dompdf
     

4. Email Attachments

   • For email attachments to work, ensure the storage directory is writable and the filament-invoices.email config is set:

     'email' => [
         'from' => 'invoices@yourdomain.com',
         'pdf_path' => storage_path('app/invoices'),
     ],
     

5. Morph Relationships

   • If using morphTo, ensure the invoiceable_type and invoiceable_id columns exist in the invoices table (they are included by default).

Debugging Tips

1. Log Invoice Creation Enable logging in the config to debug issues:

   'debug' => env('FILAMENT_INVOICES_DEBUG', false),
   

2. Check PDF Generation Test PDF generation locally before deploying:

   $pdf = $invoice->generatePdf();
   Storage::disk('local')->put('test.pdf', $pdf);
   

3. Validate Config Use php artisan config:clear if changes to filament-invoices.php aren’t reflected.

4. Clear Cached Views If template changes aren’t showing, run:

   php artisan view:clear
   

Extension Points

1. Custom Invoice Models Extend the Invoice model to add fields:

   use TomatoPHP\FilamentInvoices\Models\Invoice as BaseInvoice;
   
   class Invoice extends BaseInvoice
   {
       protected $casts = [
           'tax_exempt' => 'boolean',
       ];
   }
   

2. Hooks for Pre/Post Actions Use events to intercept invoice creation/updates:

   // In EventServiceProvider
   InvoiceCreated::listen(function ($invoice) {
       // Add custom logic (e.g., notify admin)
   });
   

3. API Endpoints Expose invoice data via Laravel API routes:

   Route::get('/invoices/{invoice}', [InvoiceController::class, 'show']);
   

4. Localization Override labels/translations in resources/lang/en/filament-invoices.php:

   return [
       'invoices' => [
           'title' => 'Bills',
       ],
   ];