Invoice Ninja Laravel Package

Getting Started

InvoiceNinja v5.13.50 is a self-hosted Laravel application rather than a drop-in composer package, so "installing" it means cloning the repo and bootstrapping the app:

• Clone invoiceninja/invoiceninja, check out v5.13.50, run composer install, copy .env.example to .env, generate the app key, then php artisan migrate --seed. This is a patch on top of v5.13.49, so an existing checkout can simply merge/pull the tag and re-run composer install + php artisan migrate.
• Start with app/Models/ and app/Repositories/ — almost every feature (invoices, quotes, payments, expenses, reports) is a Model + Repository pair, and the repository is where most of the recent patched logic lives (filters, eager loading, batched chart summaries, user-purge scoping).
• First practical use case: build a small internal integration that creates a client + invoice through the API and then triggers the PDF/email flow. That exercises the models, repositories, jobs, transformers, and the mail pipeline in one pass.
• The public HTTP API is the cleanest entry point if you are building against InvoiceNinja rather than inside it; register an API token in the UI and hit /api/v1/clients and /api/v1/invoices. Note that v5.13.50 changed the transformers that define available includes, so re-check which ?include= values your client sends.
• If you need Stripe, read the app/Services/Payment/ drivers before anything else — since v5.13.49 the minimum Stripe API version is 2025.basil, so your Stripe SDK/app config must be current.
• If you rely on cron/scheduled behaviour, read app/Console/Kernel.php (or routes/console.php) early — v5.13.50 touched the scheduler request layer, which is what drives recurring invoices, reminders, and report dispatches.

Implementation Patterns

• Repository-first work. When you extend a report or list view, add filtering to the relevant repository method rather than the controller. Filters go through app/Filters/ query filters, not ad-hoc where() calls in controllers.
• Eager-load deliberately. Follow the existing with() arrays in repositories; if a page starts throwing N+1s, fix the repository, not the Blade view. Recent releases have repeatedly patched eager-loading regressions, so treat with() as load-bearing code.
• Reporting and charts. Chart summaries are batched in a single query. If you add a dashboard widget, follow that pattern (aggregate in one query, then pivot in PHP) instead of looping per period.
• Scheduled work. Recurring invoices, reminders (including "endless" reminder chains), and cleanup tasks are driven by the scheduler. Keep your own scheduled jobs in the same registration style as the shipped ones so the v5.13.50 scheduler request-layer changes apply consistently, and make your jobs idempotent — the scheduler can re-fire after a missed run.
• API includes and transformers. Build API responses by requesting explicit include= parameters rather than expecting fat payloads. The company/account transformers were cleaned up in this release; if you add a new relation to the API, expose it as an include in the transformer rather than always serializing it.
• Offline payment sync. Record payments without a live gateway round-trip and reconcile later. Use this for cash/bank-transfer workflows and for mobile/offline clients; make sure your sync job is idempotent on the payment reference.
• Webhook and job pipeline. Invoices, emails, and PDFs are dispatched as jobs. Integration work should enqueue and let the queue worker (Horizon) handle it, rather than calling mail or PDF generation synchronously.
• Stripe driver upgrades. With 2025.basil as the minimum, pin your Stripe PHP SDK and test the payment-intent / invoice-download paths. Any code that hand-built a …/invoices/{id}/download URL should use the corrected route.
• Testing against it. Mirror the existing test conventions (tests/Feature, factories, RefreshDatabase) when you add your own. The suite still skips some FR reporting tests — don't assume French reporting is covered by CI.

Gotchas and Tips

• Treat this as a fork, not a dependency. There is no stable package API; upgrades are repo merges. Keep customizations in clearly marked files or separate service providers so you can re-apply them on the next patch (these ship frequently — v5.13.49 → v5.13.50 in a matter of weeks).
• Available-includes cleanup is the most likely API break in v5.13.50. If your client requests ?include= values on company or account endpoints, diff the transformer include lists after upgrading; some previously available includes may have been renamed or removed. Fail loudly in your client rather than silently rendering empty relations.
• Scheduler request-layer changes. If you had workarounds around cron/scheduler behaviour (custom commands, wrapper scripts, adjusted withoutOverlapping), re-verify them. Also spot-check reminders: v5.13.50 includes fixes to endless reminders, which historically have been the most fragile scheduled path.
• Purging users got new scoping. The purge path now constrains DB lock contention, which matters on large multi-tenant instances. If you script user deletions or run bulk purges, test on a copy of production and watch for lock waits; behaviour is safer but different.
• Stripe remains the sharp edge. The 2025.basil minimum is effectively a breaking change for anyone on an older API version: webhook payload shapes, payment-method handling, and invoice finalization can differ. Re-run your payment test suite against a Stripe test-mode account before deploying.
• Dependency updates in a patch release. Lockfile churn can shift transitive behaviour (Guzzle, Carbon, queue libs). Run composer update --lock-style checks and re-run your integration suite rather than assuming a no-op.
• Activity feed fixes. If you render or consume the activity feed, re-verify ordering and pagination — the API fixes touched this area and small ordering changes can break UI assumptions.
• Debugging tips: php artisan queue:failed and Horizon for mail/PDF/Stripe jobs; php artisan schedule:list and schedule:test for scheduler issues; Laravel Telescope in non-production for query inspection (very useful for spotting N+1s and lock contention); config/invoiceninja.php and the settings tables for feature toggles that override .env.
• Extension points that survive upgrades: custom PaymentDriver implementations in app/Services/Payment/, custom filters in app/Filters/, event listeners on existing model events (Invoice created/sent/paid), additional API includes via transformers, and a private composer package for your own models. Avoid editing Blade views deep in resources/views/ unless you are prepared to re-merge.
• Translation updates are cosmetic but can shift key names; if you maintain a custom locale file, diff it after upgrading.