Weave Code
Taxation Laravel Package
sylius/taxation
Sylius Taxation Component provides core models and extensible tax calculators to handle taxes for different items, zones, and tax rates in PHP applications. Part of the Sylius eCommerce ecosystem, designed for easy integration and customization.
[READ-ONLY] Taxation system with multiple categories and rates support, for PHP.
Frequently asked questions about Taxation
- How do I integrate sylius/taxation into a Laravel project without using Sylius eCommerce?
- Start by installing via Composer (`composer require sylius/taxation`) and manually bootstrapping the component in `AppServiceProvider`. Bind tax calculators to Laravel’s container (e.g., `bind(TaxCalculationInterface::class, TaxCalculation::class)`) and extend Eloquent models (e.g., `TaxCategory`, `TaxRate`) with Laravel traits like `HasFactory`. Use Laravel migrations to scaffold tables for tax rates, categories, and zones.
- Does sylius/taxation support dynamic tax rates (e.g., fetched via API at checkout)?
- Yes, but requires customization. The component’s pluggable calculator system lets you create a `TaxRateResolver` to fetch rates dynamically (e.g., from an external API). Cache resolved rates in Laravel’s cache system to avoid repeated API calls during checkout. Example: `Cache::remember('tax_rates', 3600, fn() => $api->fetchRates());`
- What Laravel versions and PHP requirements does sylius/taxation support?
- The package requires **PHP 8.1+**, aligning with Laravel 10/11. It uses Symfony components (e.g., `options-resolver`, `validator`) already bundled with Laravel, so no additional dependencies are needed. For older Laravel versions (e.g., 9.x), check the package’s `composer.json` for compatibility notes or use a legacy branch if available.
- Can I use sylius/taxation for multi-tenant Laravel apps (e.g., with Stancl or Tenancy)?
- Yes, but tenant-specific tax configurations require manual handling. Store tax rates/zones in a `tenants` table or use Laravel’s context (e.g., `tenant()->id`) to scope queries. Override the `TaxRateRepository` to filter by tenant. Example: `TaxRate::where('tenant_id', tenant()->id)->get()`. Cache tenant-specific rates to optimize performance.
- How do I test tax calculations for edge cases like zero-rated items or negative adjustments?
- Use Laravel’s testing tools to mock tax calculators and repositories. Test scenarios like `TaxRate::zero()` or negative adjustments by injecting a fake calculator in your test case: `$this->app->instance(TaxCalculationInterface::class, FakeTaxCalculator::class)`. Validate results with assertions like `$this->assertEquals(0, $order->getTaxTotal())`. Document edge cases in your test suite for compliance.
- Is sylius/taxation better than Spatie’s Tax package for Laravel?
- Choose based on needs: **sylius/taxation** offers deeper customization (e.g., zone-aware taxes, pluggable calculators) and fits complex eCommerce workflows, while **Spatie’s Tax** is simpler for basic VAT calculations. Sylius excels in multi-region tax logic; Spatie is lighter for straightforward use cases. Compare features like tax category hierarchies or API-driven rates.
- How do I expose tax data via a Laravel API (REST/GraphQL)?
- For REST, create a resource controller and use Laravel’s API Resources: `php artisan make:resource TaxRateResource`. For GraphQL, use Lighthouse to define types (e.g., `type TaxRate { id: ID! amount: Float! }`). Secure endpoints with Sanctum or Passport policies. Example: `return new TaxRateResource(TaxRate::all());` in a controller or GraphQL resolver.
- What’s the performance impact of tax calculations during high-traffic checkout flows?
- Heavy tax calculations can bottleneck checkouts. Mitigate this by **caching tax rates/zones** (e.g., `Cache::rememberForever()`) and **offloading calculations to queues** (e.g., `dispatch(new CalculateTaxes($order))`). Benchmark with Laravel’s queue workers (e.g., `php artisan queue:work`) and consider pre-calculating taxes for static rates.
- How do I migrate existing tax data (e.g., from a legacy system) into sylius/taxation?
- Use Laravel migrations to create tables, then write a data importer script. Example: `TaxRate::insert($legacyRates->map(fn($rate) => ['name' => $rate->name, 'amount' => $rate->value]))`. For complex mappings, use Eloquent’s `create()` or `updateOrCreate()`. Validate data integrity post-migration (e.g., `TaxRate::count()` matches legacy records).
- Does sylius/taxation support tax certificate generation or audit trails?
- The component provides the data models but requires custom logic for certificates/audit trails. Use Laravel’s **events** (e.g., `TaxCalculated`) to trigger side effects like logging or PDF generation (e.g., with DomPDF). Store audit logs in a `tax_audit_logs` table with timestamps, user IDs, and calculation details. Example: `event(new TaxCalculated($order, $taxTotal));`
Weaver
How can I help you explore Laravel packages today?