Laravel Accounting Laravel Package

Getting Started

This is a Filament plugin that drops accounting primitives (accounts, transactions, starting balances, reports) into a panel as resources and pages. It is not a headless accounting library — the day-to-day value is the UI: you get CRUD screens and report pages, and you shape them with Filament policies, form overrides, and navigation config.

Pick your version line first. This is the single most important step right now:

v2.0.0-alpha is a pre-release with an explicitly unstable API. Treat it as a spike or a greenfield-only bet, and pin the exact alpha in composer.json ("2.0.0-alpha" rather than ^2.0@alpha) so a mid-sprint alpha bump can't silently rewrite the Schema definitions you're building against.

Minimal steps (v2 path):

1. Install with the @alpha stability flag above; confirm composer why-not shows no Filament v3 packages left in the graph.
2. Register the plugin on your panel in app/Providers/Filament/AdminPanelProvider.php using the panel plugin API (->plugin(...)), then load /admin and check the navigation group appears.
3. Run the package migrations and publish config/assets if the service provider exposes them (vendor:publish --tag=... after checking php artisan vendor:publish --list).
4. Create a second panel or use canAccessPanel() early, because the accounting resources land in whatever panel registers the plugin.

First use case: don't start with reports. Create two accounts (e.g. a cash account and an income account), post one transaction between them, and verify the balances move. That single loop exercises accounts, transactions, and starting balances together, and it's where misconfiguration shows up first — most "the report is empty" issues trace back to a transaction that never actually posted or a chart of accounts with no opening balances.

Where to look first: the TransactionResource and its policy, the report page classes, and the starting-balance page. Those three are exactly what v2 changed (Schema API, removed Blade components, canViewAny() gating), so they're where your overrides will live and where upgrades will bite.

Implementation Patterns

Treat resources as extension surfaces, not as scaffolding to copy. With Resource::getForm(Form|Schema $schema)-style signatures in v4/v5, the idiomatic pattern is to extend the package resource and modify the schema, not to duplicate it into app/Filament/Resources. Keeping your subclass thin (parent::form($schema)->schema([...])) means the v2 → v2.0.0 stable diff stays small.

Gate access through the policy, not the navigation. The v1.6.2 security fix makes report pages depend on TransactionResource::canViewAny(), and validates submitted account ids server-side. Practical consequence: if you've been hiding accounting from non-finance users by setting ->navigationGroup(null) or shouldRegisterNavigation(false), that is no longer sufficient — reports are gated on the transaction policy. Register a real policy:

// AuthServiceProvider / or auto-discovery
TransactionResource::class => TransactionPolicy::class,

and have viewAny() return the finance-role check. Then add a feature test asserting a non-finance user gets 403 on the report page, not just a hidden nav item. Re-verify this after upgrading from any 1.6.x — the advisory means the pre-patch behaviour was permissive.

Multi-panel setups. Registering the plugin in more than one panel gives you two independent resource trees over the same tables — fine, but each panel gets its own navigation, slug prefix, and policies resolve per-panel context. If you want a read-only reporting panel alongside an operations panel, subclass the resources and flip canCreate()/canEdit() in the policy via the panel id.

Starting balances are stateful UI. The v2 fix for "starting balances and report filters not saving their state on Filament v4+" tells you these pages use Livewire state that previously didn't persist across navigation. Pattern: keep report configuration (date range, account selection) in the page's own state or a query string, and drive exports/recurring reports from a dedicated service that takes those values as arguments — don't rely on the page's component state surviving a redirect back into the report.

Integration tips that pay off:

• Seed a chart of accounts in a seeder and reference accounts by a stable code/slug in your own code, not by hardcoded ids. The package validates submitted account ids, so passing ids around in your own forms is fine but fragile.
• Wrap posting logic (transaction + balancing entries) in a DB transaction and a small action class. You will eventually need to post transactions from a job, an importer, or an observer, and you don't want that logic living only inside a Filament form.
• For dashboards, call report queries through the package's services/actions rather than duplicating SQL in a widget.
• Write one Filament panel test per resource (livewire(ManageTransactions::class)->assertCanSeeTableRecords(...)) — v2 added panel tests upstream, which is a hint that the UI layer is where regressions happen, and you'll be leaning on those tests to validate your alpha → stable upgrade.

Gotchas and Tips

The pre-release status is the headline gotcha. 2.0.0-alpha can change its API before 2.0.0. Consequences to plan for: pin the exact version, don't ship it to a client's production books yet, and if you do build on it, keep your overrides in a small number of files so the eventual diff is mechanical. Budget a real upgrade ticket for alpha → stable.

Filament v3 is a hard stop. v2 drops it entirely; there's no compatibility shim. If any other plugin in the panel still requires Filament v3, you cannot mix — you stay on ^1.6.2 (which does carry the security fixes) until that plugin ships v4 support. Check the whole panel's dependency graph before starting, not after composer update fails.

awcodes/filament-table-repeater removal is a two-sided change. If your code imported that package only transitively, you can remove it from composer.json and pick up the dependency slim-down. If you used it in your own forms, its removal from this package does nothing for you — you still need it, or you migrate those forms to Filament's built-in table repeater yourself. Grep your app/ for TableRepeater before assuming you're clear.

Schema API breakage is the most likely upgrade injury. "Package forms are built on Filament's Schema API. If you extended the package's resources or pages, update your overrides." In practice this means any form(Form $form): Form override becomes the Schema-based signature, and ->schema([...]) positioning changes. Symptoms of a missed override: form renders empty, sections collapse, or a TypeError on the method signature during php artisan filament:cache-components. Run php artisan optimize:clear and filament:cache-components after upgrading — cached components mask signature errors in confusing ways.

Blade component removal. v2 replaced Blade components that Filament v4 removed in the report and starting-balance views. If you published those views and customized them, your published copies still reference deleted components and will throw "component not found" at render time. Delete or re-publish your published views before diffing your customizations back in.

Debugging empty or wrong reports, in order: (1) does the user pass canViewAny() on TransactionResource? (2) do the accounts have opening/starting balances recorded, and do those pages persist state correctly on v4+? (3) are the account ids in the filter actually valid and owned by the current tenant/panel? (4) is there a where on a date column being fed a locale-formatted string? The first two account for most reports, and both are v2-touched areas — so retest them specifically after any alpha bump.

Livewire 4 on Filament v5 is a broader blast radius than this package. If you're on the v5/Livewire 4 path, every other panel plugin and any custom Livewire component in your app needs to be compatible too. Stage the Filament upgrade separately from the accounting package upgrade so you can attribute failures.

Extension points worth knowing now: the policy layer (viewAny, create, update on the resources) is the cheapest and most stable customization; resource/page subclassing is the intended form-level extension but the most exposed to v2 API churn; publishing and editing views is the most fragile (see Blade removal above) — prefer schema overrides over view overrides wherever both are possible.