Laravel Taxify Laravel Package

Getting Started

• Install: composer require omaralalwi/laravel-taxify, then publish the config with php artisan vendor:publish --tag=taxify-config (confirm the exact tag/provider in the README for your pinned version). The package auto-discovers its service provider on Laravel 9+; older apps need the provider registered in config/app.php.
• Look first at config/taxify.php. That file is the whole mental model: default rate, tax classes/rate definitions, and the rounding/precision setting that the recent releases keep refining. If the config keys don't match the README, trust the installed config file — the package has moved fast across 2.x.
• First use case: compute tax on a single amount. Resolve the calculator from the container (or use the facade/helper the README documents) and call the calculate method with an amount and a rate/class. Print the returned tax and gross. If the numbers come back as rounded values rather than raw decimals, that's expected — see Gotchas.
• Before wiring it into an order flow, write a throwaway test that asserts a handful of known amounts (e.g. 100 @ 15% → 15.00). That single test becomes your regression net for the rounding changes landing in patch releases.

Implementation Patterns

• Don't call the facade from models. Register the calculator as a singleton and inject it into a dedicated TaxCalculator/PricingService, then have that service return a small value object (TaxBreakdown with net, tax, gross, rate). This keeps rounding policy in one place and makes it swappable in tests.
• Snapshot the rate on the line item. Rates are configuration, not history. Persist tax_rate, tax_amount, and tax_inclusive on order lines at write time so a config change or upgrade never restates a historical invoice.
• Explicit inclusive/exclusive mode per call. For tax-inclusive pricing the derived tax is gross - (gross / (1 + rate)), and for exclusive it's net * rate. Don't infer the mode from context — pass it, otherwise cart previews and final invoices drift apart.
• Round at the level you bill at. If you display per-line tax, round per line and sum; if you display one tax total, round once at the total. Mixing the two produces penny drift that support tickets are made of. Given v2.0.4 touches rounding, pin your choice in code and cover it with tests.
• Resolve rates through one resolver. A TaxRateResolver interface (country → zone → class → rate) backed by config or a DB table keeps multi-region logic out of controllers and makes it trivial to add a new jurisdiction.
• Tests: bind a fake calculator or set config rates in setUp()/php artisan config:cache-free test env. Assert on integer minor units (cents) rather than floats to avoid brittle assertions.
• Presentation: format at the edge only. Keep the service returning numeric values; let Blade/Inertia/API resources handle number_format and currency symbols.

Gotchas and Tips

• v2.0.4 changes returned-number rounding. Any test asserting exact floats or exact string formatting may flip. Re-run your amount matrix after upgrading and diff the outputs before deploying; also reconcile any tax figures the package computes that you don't snapshot.
• Floats. PHP floats will bite on large sums and multi-line carts. Convert to integer minor units as early as possible, or use bcmath in your own wrapper around the package rather than assuming the package does it for you.
• php artisan config:cache is mandatory in production. Rate changes in config/taxify.php silently do nothing on a cached deploy until you re-cache. Add it to your deploy script and your "tax rate is wrong" runbook.
• Config changes are not migrations. If you move rates into the DB, keep a deterministic seed and treat the config file as defaults only, or you'll get different behaviour between fresh and existing environments.
• Order of rounding operations matters more than the rounding mode. Document whether you round half-up or banker's, and whether you round before or after summing. The package's choice may not match your accountant's expectation.
• Extension points: the config file, the container binding for the calculator, and (where exposed) custom tax classes/resolvers. Prefer binding your own implementation over editing vendor files or reaching into internals via reflection.
• Debugging: dump the resolved config (config('taxify')) and the rate the resolver returned for the failing case. Nine times out of ten the bug is a stale config cache, a missing rate for the buyer's zone, or a mismatched inclusive/exclusive flag — not the math.
• Watch the changelog for patch releases. This package ships behavioural refinements (like v2.0.4's rounding) in patch versions, so treat upgrades as minor-behaviour-change events: run the amount matrix, not just the test suite.