Vat Calculator Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Compatibility: The package is designed for Laravel (via facade) but also supports standalone PHP, making it a strong fit for Laravel-based e-commerce, SaaS, or subscription platforms. The BillableWithinTheEU trait integrates seamlessly with Laravel Cashier (pre-v13), addressing a critical gap in EU VAT compliance for subscription billing.
• Modular Design: Core functionality (tax calculation, VAT validation) is decoupled from Laravel-specific features (e.g., Cashier integration), allowing selective adoption. The package’s configuration-driven approach (e.g., vat_calculator.php) enables customization without forking.
• EU MOSS/OSS Alignment: Explicitly addresses EU VAT rules, including postal-code-based rate adjustments (e.g., German reduced rates for certain regions) and B2B vs. B2C differentiation, which is critical for compliance with EU VAT Directive 2006/112/EC and MOSS/OSS regulations.
• Extensibility: Supports custom VAT rules via configuration, allowing businesses to override default rates (e.g., for specific product categories or exemptions).

Integration Feasibility

• Low Friction for Laravel Apps:
  • Facade-based API (VatCalculator::calculate()) requires minimal code changes.
  • Validation Rule (ValidVatNumber) integrates directly with Laravel’s validator.
  • Cashier Trait (BillableWithinTheEU) provides a drop-in replacement for taxPercentage, reducing refactoring effort.
• Standalone PHP Support: Can be used in non-Laravel PHP apps (e.g., legacy systems, microservices) with minor adjustments (e.g., instantiating VatCalculator manually).
• Third-Party Dependencies:
  • VIES SOAP API: For VAT validation, introduces external dependency risk (API downtime, rate limits).
  • HMRC API: Required for UK VAT validation, adding authentication complexity (OAuth2 via .env).
  • No hard dependencies on other Laravel packages (e.g., no Guzzle, Symfony HTTP client required).

Technical Risk

Key Questions for TPM

1. Compliance Requirements:
   • Does the business operate in multiple EU countries? If so, does the package’s postal-code-based rate detection cover all edge cases (e.g., German reduced rates)?
   • Are there non-EU markets (e.g., UK post-Brexit, Switzerland)? The package supports UK VAT but may need adjustments for other regions.
2. Cashier Version:
   • Is the app using Laravel Cashier v13+? If yes, how will tax logic be handled without the BillableWithinTheEU trait?
3. VAT Validation Workflow:
   • Is real-time VAT validation required for all transactions, or can format validation (isValidVatNumberFormat) suffice for initial checks?
   • What’s the fallback strategy if the VIES/HMRC APIs are down? (e.g., manual review, cached responses)
4. Customization Needs:
   • Are there product-specific VAT exemptions (e.g., digital vs. physical goods) not covered by the package?
   • Does the business need audit logs for VAT calculations? The package doesn’t provide this out-of-the-box.
5. Scaling:
   • How many VAT validation requests are expected per day? The SOAP API may have rate limits.
   • Will caching (e.g., Redis) be implemented for VAT rates or validation responses?

Integration Approach

Stack Fit

• Primary Use Case: Laravel-based e-commerce, SaaS, or subscription platforms selling to EU customers.
• Secondary Use Case: Standalone PHP applications needing VAT calculation (e.g., legacy systems, microservices).
• Compatibility:
  • Laravel: Full integration via facade, validation rule, and Cashier trait.
  • Non-Laravel PHP: Requires manual instantiation of VatCalculator (minimal effort).
  • Symfony: Could be adapted with minor changes (e.g., DI container binding).
  • Other Frameworks: Not directly supported; would require wrapper logic.

Migration Path

Compatibility

• PHP Version: Requires PHP 7.3+ (no issues for modern stacks).
• Laravel Version: Optimized for Laravel 6+; may need adjustments for older versions (e.g., Cashier v6 support).
• Database: No schema changes required.
• Dependencies:
  • SOAP Extension: Required for VAT validation (enabled by default in PHP).
  • cURL/HTTP Client: Used for HMRC UK API (if enabled).
  • No heavy dependencies (e.g., no queue workers, event listeners by default).

Sequencing

1. Phase 1: Core Tax Calculation
   • Replace manual VAT logic with VatCalculator::calculate().
   • Validate against business country code and postal codes.
2. Phase 2: VAT Validation
   • Integrate ValidVatNumber rule into checkout forms.
   • Implement fallback for VIES API downtime (e.g., cached responses or manual review).
3. Phase 3: Cashier Integration (if applicable)
   • Apply BillableWithinTheEU trait (only for Cashier < v13).
   • Test B2B vs. B2C tax differentiation.
4. Phase 4: UK VAT Support
   • Register with HMRC and configure .env for UK VAT validation.
5. Phase 5: Performance Optimization
   • Cache VAT rates and validation responses (e.g., Redis).
   • Implement retry logic for SOAP API failures.

Operational Impact

Maintenance

• Configuration-Driven Updates:
  • VAT rates are configurable (no code changes needed for EU updates).
  • Upgrade Path: Follow the UPGRADE.md guide; breaking changes are rare (e.g., Cashier v13+ incompatibility).
• Dependency Management:
  • VIES/HMRC APIs: Monitor for changes (e.g., rate limits, authentication updates).
  • SOAP Client: May require updates if EU changes their API schema.
• Custom Rules:
  • Business-specific VAT rules (e.g., exemptions) must be manually added to the config.

Support

• Troubleshooting:
  • VAT Validation Failures: Check if VIES/HMRC APIs are down (package provides graceful fallbacks).
  • Cashier Issues: Ensure compatibility with the installed version (v13+ requires work