Filament Invoices Laravel Package

Technical Evaluation

Architecture Fit

• FilamentPHP Alignment: The package is tightly coupled to FilamentPHP, now at v5 in the current release (v5.0.0). Filament remains the primary UI surface (admin panel, widgets, settings hub), so it is only appropriate for projects standardising on Filament for admin interfaces. Note the version jump: the packaged target moved from Filament v3 → v5 across two majors.
• Laravel Baseline Moved: Now requires Laravel 12 / 13 and PHP 8.2+. Laravel 10 (and, by implication, Laravel 11) is no longer the supported floor for the current line.
• Dual-Track Release Model: A maintained v4 branch exists for Filament v4 consumers ("Filament v4 users: stay on 4.x"). This is a meaningful architectural signal — the vendor is explicitly supporting two Filament majors in parallel rather than forcing an immediate lift-and-shift.
• Domain-Specific: Still specialised for invoicing/payments, fitting SaaS, B2B, and e-commerce platforms with structured financial workflows.
• Extensibility: Unchanged — Factory Pattern for templates and Morph Maps for polymorphic relationships allow customisation without core modification. The release loosens a morph constraint (see below), which improves fit for non-standard billable models.
• Hardening Over Features: v5.0.0 is predominantly a compatibility + defect-release, not a feature release. There is no new domain capability to re-evaluate; the value is in reduced fragility.

Integration Feasibility

• Dependency Floor Raised:
  • Filament v5 (core dependency; v4 supported only via the v4 branch).
  • PHP 8.2+ (was 8.1+).
  • Laravel 12 / 13 (was 10.x).
  • DomPDF unchanged for PDF generation; optional Laravel Notifications and Cashier/Stripe still apply.
• Polymorphic Constraint Removed (material): The invoice page now works for billed models without a locations() relation. Previously an implicit assumption; this widens the set of integrable billable entities and removes a likely customisation fork.
• Null/Empty-State Tolerance Improved: Payments on invoices with no currency and empty item rows no longer fail; saving settings with empty optional fields no longer fails. These were integration-time footguns (particularly for greenfield tenants without currency defaults), now closed.
• Database Schema: Still assumes standard Laravel conventions (invoices table). Schema migration risk against existing custom invoice models is unchanged.
• API-Friendly: Facade-based design (Invoice::create()) unchanged; headless use remains possible but still requires a custom UI layer.

Technical Risk

• Filament Version Lock — Escalated: The core risk identified previously has materialised. The package now tracks Filament v5; Filament v3 is no longer served by the current line. Any team on Filament v3 faces a two-major Filament upgrade to consume this release.
• Triple Coupling: The upgrade surface is now Filament major × Laravel major × PHP minor simultaneously. Laravel 12 + PHP 8.2 + Filament v5 must move together, which makes this a platform upgrade programme rather than a dependency bump.
• Backport Policy Is Undefined (new risk): The v4 branch exists, but it is not stated whether it receives bug fixes (e.g., the four defects fixed here) or only security patches. Teams pinned to v4 may be running known-broken null-currency and empty-item paths.
• Version Churn Cost: Three package majors tracking three Filament majors implies recurring, non-trivial upgrade work. Budget for a repeat cycle at Filament v6.
• PDF Generation Overhead: Unchanged — DomPDF deployment footprint and single-threaded generation remain the principal performance risk.
• Multi-Currency Complexity: Partially mitigated. The crash on missing currency is fixed; the business logic risk (exchange rates, tax rounding) is not addressed and still requires a dedicated money package.
• Residual (Not Addressed): Email delivery via Laravel's mail system (SMTP misconfiguration), and compliance/tax-format coverage remain unverified.

Key Questions

1. Filament Upgrade Path: What is the concrete effort to move from Filament v3 → v5 (via v4)? Are we willing to fund that now, or do we ship on the v4 branch?
2. v4 Branch Support Policy: Will v4 receive the four bug fixes shipped in v5.0.0? What is the stated maintenance window and EOL date for v4?
3. Laravel 11 Gap: Is Laravel 11 formally unsupported, or merely untested? This determines whether we can stay on L11 as an interim step.
4. Test Suite Enforcement: "Full test suite" is stated — is it CI-enforced on every PR and run against both v4 and v5 branches? This is the single best proxy for long-term maintenance risk given the low community footprint.
5. Compliance: Does the package support required tax/invoice formats (VAT, local regulations) out of the box? Unchanged and still unvalidated.
6. Payment Integration: Is there a roadmap for native gateway support (Stripe, PayPal) beyond basic payment records? Unchanged.

Integration Approach

Stack Fit

• Ideal For:
  • Laravel 12/13 + Filament v5 SaaS platforms (subscription services, freelance tooling).
  • Projects needing admin-heavy invoice management with minimal frontend effort.
  • Platforms with heterogeneous billable models — the locations() decoupling removes a prior fit blocker.
• Less Ideal For:
  • Headless APIs or non-Filament Laravel apps (custom UI layer still required).
  • Projects on Laravel 10/11 or Filament v3 — significant platform upgrade required first.
  • Real-time / high-frequency billing systems.

Migration Path

1. Decide the Track First (new, gating step):
   • Track A — v5.0.0: requires Filament v5 + Laravel 12/13 + PHP 8.2+.
   • Track B — v4 branch: retain Filament v4; accept an unconfirmed bug-fix backport position.
   • Track C — deferred: stay on the prior package line; no fixes for the null-currency / empty-item / empty-settings defects.
2. Prerequisites:
   • Confirm Laravel 12/13 and PHP 8.2+ on the target environment.
   • Upgrade Filament to v5 (v3 → v5 requires an intermediate v4 hop).
   • Set up DomPDF (composer require barryvdh/laravel-dompdf).
3. Core Integration:
   • Publish and configure package assets:

     php artisan vendor:publish --provider="Tomato\FilamentInvoices\FilamentInvoicesServiceProvider"
     

   • Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

     $panel->plugins([
         \Tomato\FilamentInvoices\FilamentInvoicesPlugin::make(),
     ]);
     

4. Customization:
   • Extend templates via the InvoiceTemplateFactory or override views in resources/views/vendor/filament-invoices.
   • Hook into events (InvoiceCreated, InvoiceSent) for custom logic.
   • Re-validate any local workaround previously added for missing-currency or locations() assumptions — those patches are now redundant.
5. Testing:
   • Validate PDF generation, email attachments, and multi-currency calculations in staging.
   • Explicitly regression-test: settings save with empty optionals, invoices with empty item rows, billed models with no locations().

Compatibility

• Laravel: v12/13 for the current line; Laravel 10/11 requires the older package line.
• Filament: v5 for the current line; v4 via the v4 branch; v3 no longer supported by the current line.
• PHP: 8.2+ (raised from 8.1+).
• Database: Eloquent-based; ensure invoices migrations don't conflict with existing schemas. No schema changes flagged in this release.

Sequencing

1. Phase 0 — Platform Upgrade (new, largest cost): Upgrade PHP → 8.2+, Laravel → 12, Filament v3 → v5. Treat as an independent, shippable milestone with no invoice-package changes.
2. Phase 1 — Basic Setup: Package install (v5.0.0 or v4 branch), plugin registration, template configuration.
3. Phase 2 — Core Workflows: Invoice creation, PDF generation, email sending.
4. Phase 3 — Advanced Features: Multi-currency (with spatie/money), payment integrations, custom templates.
5. Phase 4 — Performance Tuning: PDF caching, queued/batch generation for bulk invoices.

Operational Impact

Maintenance

• Vendor Updates (elevated burden): Three package majors now track three Filament majors. Assume a non-trivial upgrade exercise at each Filament major and budget for it in the roadmap rather than treating it as incidental.
• Dual-Branch Tracking: If on the v4 branch, actively monitor whether fixes are backported; do not assume parity with v5.
• Test Suite as an Asset: The new full test suite materially improves the maintenance story for a low-community package — it makes forking and self-patching far more tractable. Confirm it is CI-enforced.
• Dependency Management: DomPDF and Filament plugins still need periodic updates; the Laravel 12/13 pairing narrows the compatible matrix further.
• Custom Code: Extensions (custom templates, events, any interim workarounds) must be version-controlled and documented. Remove now-obsolete workarounds around currency/item edge cases.

Support

• Community: Still limited (no change in footprint reported); no official support channel. The addition of a full test suite, new cover, and screenshots is a modest but genuine maturity signal.
• Multi-Branch Clarity: The explicit v4/v5 split is good support communication — but the absence of a stated backport/EOL policy is a gap worth raising directly with the maintainer.
• Debugging: Log invoice events and PDF generation steps; use Filament's debug tools for UI issues. Fewer null-state crash paths means less time spent on defensive diagnostics.

Scaling

• Performance Bottlenecks: Unchanged. DomPDF is single-threaded — queue bulk generation (queue:work). Index status, currency, created_at at volume.
• Horizontal Scaling: Stateless design (except PDF generation) allows scaling Laravel workers. Cache invoice templates and settings.
• Multi-Tenancy: Polymorphic relationships supported; the locations() decoupling specifically helps tenants whose billable models are structurally minimal. Still verify isolation with stancl/tenancy.
• Platform Headroom: Laravel 13 support implies alignment with PHP 8.3/8.4 runtimes over time — modestly better long-term scaling runway, contingent on Filament v5's own runtime support.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1–2 Days: Filament plugin system and package features (unchanged).
  • 3–5 Days: Core workflows (CRUD, PDFs, emails) with basic customisation.
  • +2–5 Days (new): Filament v5 delta for developers coming from v3/v4, plus unlearning any workarounds now fixed upstream.
• Key Learning Curves:
  • Filament widget system and settings hub (v5 APIs).
  • Morph Maps for polymorphic invoice relationships — note the relaxed locations() assumption.
  • DomPDF customisation for template tweaks.
• Documentation Gaps:
  • No stated backport/EOL policy for the v4 branch.
  • No explicit statement on Laravel 11 support status.
  • No documented v3 → v5 migration guide for the package itself.
  • Limited examples for advanced use cases (multi-currency tax logic).