Opensalestax Laravel Package

Technical Evaluation

Architecture Fit

• Stateless Wrapper: The SDK is a thin, stateless HTTP client (~200 LOC) that delegates all tax logic to the OpenSalesTax engine. This aligns well with microservices or modular architectures where tax calculation is a discrete service.
• Decoupled Design: No embedded business logic or caching—ideal for systems requiring strict separation of concerns (e.g., Laravel apps where tax logic is externalized).
• Precision Handling: Uses decimal strings (not floats/cents) to avoid rounding errors, which is critical for financial calculations. This requires careful integration with existing monetary systems (e.g., Laravel Cashier, Stripe).
• Extensibility: Supports PSR-18 HTTP clients (default: Guzzle 7), enabling customization for enterprise needs (e.g., retries, middleware).

Integration Feasibility

• Laravel Compatibility:
  • Service Provider: Can be bootstrapped as a Laravel service provider with dependency injection (e.g., bind(Client::class, fn() => new Client(config('opensalestax.url')))).
  • Facade: Wrap the client in a facade (e.g., OpenSalesTax::calculate()) for cleaner syntax.
  • Service Container: Inject Client into controllers/services via constructor injection.
• Database Sync: No ORM or database layer—pure API calls. Can integrate with Laravel’s queue system for async tax calculations if needed.
• Event-Driven: Can emit events (e.g., TaxCalculated) after calculations for downstream processing (e.g., tax reporting).

Technical Risk

• Engine Dependency:
  • Self-Hosting Requirement: The SDK requires a self-hosted OpenSalesTax engine (v0.59.0+ for shipping support). This adds operational complexity (infrastructure, updates, scaling).
  • Version Pinning: Must align SDK and engine versions (e.g., SDK ^0.1 + engine v0.20+). Mismatches risk breaking changes.
• Precision Handling:
  • Decimal Strings: Requires conversion from Laravel’s typical integer-cents or float systems (e.g., Money packages like league/money). Example:

    $amount = (string) ($cents / 100); // "100.00" from 10000 cents
    

  • Rounding: Laravel’s round() or bcmath may be needed to avoid precision loss.
• Error Handling:
  • Custom Exceptions: Laravel’s exception handler must be configured to log/render OpenSalesTaxException subclasses (e.g., OpenSalesTaxApiException).
  • Retry Logic: Network failures (OpenSalesTaxNetworkException) may need retries (e.g., Laravel’s retry helper or a queue job).
• Shipping Support:
  • Feature Detection: Shipping calculations require engine v0.59.0+. Must check $client->capabilities()->features->shippingFirstClass at runtime.
  • Backward Compatibility: Existing calculate() calls remain unchanged, but new code must handle null shipping responses.

Key Questions

1. Engine Hosting:
   • Who hosts the OpenSalesTax engine? (Self-managed? Kubernetes? Serverless?)
   • How will engine updates be managed (e.g., CI/CD pipelines)?
2. Precision Strategy:
   • How will decimal strings integrate with existing monetary systems (e.g., Stripe, PayPal, or Laravel Cashier)?
   • Will a custom Money class be needed to bridge the gap?
3. Performance:
   • What are the latency requirements for tax calculations? (Engine API calls may add ~100–500ms.)
   • Should responses be cached? (Note: SDK discourages caching; consumers must implement their own.)
4. Error Resilience:
   • How will failed engine requests be retried or logged? (e.g., Sentry integration for OpenSalesTaxNetworkException.)
5. Shipping Workflow:
   • Is shipping tax support a priority? If so, ensure engine v0.59.0+ is deployed.
   • How will shipping amounts be passed from Laravel (e.g., cart totals) to the SDK?
6. Compliance:
   • How will tax calculation results be audited or logged for compliance? (e.g., store CalculateResponse in a database.)
7. Testing:
   • How will integration tests verify tax calculations? (Mock the engine or use a test instance?)
   • Are there edge cases (e.g., invalid ZIPs, negative amounts) that need custom validation?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Service Container: Register the Client as a singleton or context-bound instance.
  • HTTP Client: Leverage Laravel’s built-in Guzzle client (PSR-18 compliant) to avoid external dependencies.
  • Configuration: Store engine URL, API key, and timeout in config/opensalestax.php:

    'engine' => [
        'url' => env('OPENSALESTAX_URL', 'http://localhost:8080'),
        'api_key' => env('OPENSALESTAX_API_KEY'),
        'timeout' => 10.0,
    ],
    

  • Events: Dispatch TaxCalculated events after calculations for analytics/reporting.
• Monetary Systems:
  • Use a library like league/money or moneyphp/money to handle decimal strings. Example:

    use Money\Money;
    $money = Money::USD(10000); // 100.00 USD
    $amount = (string) $money->getAmount() / 100;
    

• Shipping Integration:
  • Extend cart/checkout logic to pass shipping details to Client::calculate():

    $shipping = new OpenSalesTax\Shipping(
        amount: '12.50',
        method: 'standard',
        separatelyStated: true
    );
    $result = $client->calculate($address, $lineItems, $shipping);
    

Migration Path

1. Phase 1: Proof of Concept
   • Deploy OpenSalesTax engine (Docker or Kubernetes).
   • Integrate SDK into a single route/controller (e.g., /api/tax-calculate).
   • Test with hardcoded ZIPs/amounts to verify responses.
2. Phase 2: Core Integration
   • Register Client in Laravel’s service container.
   • Replace existing tax logic (e.g., hardcoded rates) with SDK calls.
   • Add error handling middleware for OpenSalesTaxException.
3. Phase 3: Full Rollout
   • Integrate with cart/checkout flows (e.g., pass line items from Laravel Nova or Livewire).
   • Implement shipping tax support if needed (check engine capabilities).
   • Add caching layer (e.g., Redis) for frequent calculations (despite SDK’s discouragement).

Compatibility

• Laravel Versions: Compatible with Laravel 10+ (PHP 8.2+). Tested on PHP 8.2–8.4.
• Dependencies:
  • Guzzle 7: Laravel’s default HTTP client works out-of-the-box.
  • No Conflicts: Minimal dependencies (only guzzlehttp/psr7 if not using Laravel’s client).
• Database: No schema changes required. Store tax results in JSON columns if needed for auditing.

Sequencing

1. Deploy Engine: Set up OpenSalesTax engine (Docker recommended).
2. Configure SDK: Install via Composer and configure Laravel bindings.
3. Basic Calculations: Implement calculate() for line items.
4. Error Handling: Add middleware/handlers for OpenSalesTaxException.
5. Shipping (Optional): Enable shipping tax calculations if engine v0.59.0+ is used.
6. Testing: Write integration tests with mocked engine responses.
7. Monitoring: Log calculations and errors (e.g., Sentry for exceptions).

Operational Impact

Maintenance

• Engine Updates:
  • Monitor OpenSalesTax engine releases for breaking changes.
  • Pin SDK and engine versions in composer.json and deployment manifests.
  • Test new engine versions in staging before production updates.
• SDK Updates:
  • Minor updates (e.g., 0.1.x → 0.2.x) are backward-compatible. Major updates may require testing.
  • Use composer require ejosterberg/opensalestax:^0.1 to auto-update patch/minor versions.
• Dependency Management:
  • Guzzle 7 is stable, but monitor for Laravel HTTP client changes.
  • No vendor lock-in; PSR-18 compliance allows swapping HTTP clients.

Support

• Troubleshooting:
  • Engine Issues: Check engine logs (docker logs opensalestax-engine) for failures.
  • Network Errors: Verify engine URL, API key, and firewall rules.
  • Validation Errors: Handle OpenSalesTaxValidationException for bad inputs (e.g., invalid ZIPs).
• Debugging Tools:
  • Enable Guzzle middleware to log