Getting Started

Install the package with Composer using the Packagist name from the repo README (simplepark/laravel-invoices; confirm exact vendor/package name before adding to composer.json).
Publish the package config/views/templates as documented, then inspect config/invoices.php first: seller/company details, VAT defaults, currency, template selection, and PDF/storage options usually live there.
Use v4.1.1 or newer for new work. It is a patch release from v4.1.0 and only fixes the Of which :percentage% VAT string; there are no breaking changes or deprecations noted.
First use case: generate a VAT invoice from a few line items, render/download the PDF or HTML, and verify subtotal, VAT summary, and total. This exercises config, templates, VAT calculation, and output storage in one pass.
Keep a small local fixture invoice with mixed VAT rates and a zero/exempt line. Re-render it after every package upgrade.

Implementation Patterns

Map your domain models to invoice line items rather than passing Eloquent models directly into templates. Keep invoice generation as a service/action that builds a snapshot of customer, seller, lines, VAT rates, and totals.
Store money consistently. Prefer integer minor units or decimal strings end-to-end; format only at the presentation layer. Let the package calculate VAT summaries where possible instead of duplicating arithmetic in controllers.
Generate invoices in a dedicated controller/job: create invoice data, render PDF/HTML, store the file (private disk recommended), and persist the invoice record/path. Stream or download from a separate response action.
Use the package’s published templates/views as the extension point. Override layout, logo, footer, and VAT wording there rather than editing vendor files. If you support multiple locales, keep translation keys for VAT labels aligned with the package placeholders.
For queued or bulk invoicing, render PDFs in jobs and keep the HTTP request thin. Add feature tests that assert rendered HTML contains expected customer, VAT, and total strings.
For day-to-day admin workflows, add a “preview invoice” route before final download. It catches template/config mistakes without creating stored PDFs.
Treat generated PDFs as immutable snapshots. If order data changes later, the invoice should still show the values used at generation time.

v4.1.1 fixes the Of which :percentage% VAT label. If you have custom invoice templates or translations, check whether they override that string. Republish/merge views carefully rather than blindly overwriting local customizations.
If tests assert exact VAT summary wording, update expectations for the corrected string. Also test multi-rate and zero-rate invoices, not just the default 21% case.
VAT rounding can differ between line-level and invoice-level calculations. Pick one policy, verify it against your accounting requirements, and keep it consistent across credit notes and refunds if you generate them.
After changing config or published views, clear caches: php artisan config:clear, php artisan view:clear, and rebuild caches in deployment. Config caching can hide local changes.
PDF generation often fails on storage permissions, missing fonts, or temp directory issues. Test in the same container/runtime as production, and store PDFs on a private disk with explicit retention rules.
When upgrading, run composer update for the package, then render the fixture invoice and compare VAT labels, totals, and layout. v4.1.1 is low risk, but visual output is the real regression surface for invoice packages.
Use the package’s extension points—config, templates, translations, and line/VAT objects—before reaching for forks. If you need a custom VAT label, prefer translation overrides so future patch releases remain easy to apply.