- How do I install dragonbe/vies in a Laravel project?
- Run `composer require dragonbe/vies` in your project directory. The package provides a `Vies` class that you can instantiate directly or wrap in a Laravel service provider for dependency injection. No additional configuration is required unless you need to customize the SOAP client.
- Which Laravel versions does dragonbe/vies support?
- The package is officially tested with Laravel 8+ and requires PHP 8.0+. It follows Laravel’s HTTP facade and service container patterns, so integration with older versions (e.g., Laravel 7) may require minor adjustments, but no breaking changes exist for modern Laravel apps.
- Can I cache VIES responses to reduce API calls?
- The package itself doesn’t include caching, but you can manually cache responses using Laravel’s cache drivers (Redis, Memcached, etc.). Store the `CheckVatResponse` object or its critical fields (e.g., `valid`, `countryCode`) to comply with VIES API rate limits (unofficial 1 call/second).
- How do I handle Cypriot (CY) VAT numbers starting with '6'?
- The package supports CY VAT numbers, but explicitly test numbers starting with '6' (e.g., `6XXXXXX`) in your validation logic. The VIES API may return unexpected results for these, so combine with local validation rules or fallback checks if needed. Add test cases for this edge case in your suite.
- What happens if the VIES API returns HTTP 147 (heartbeat failure)?
- HTTP 147 indicates a VIES API heartbeat issue. Implement retry logic (e.g., exponential backoff) or fallback to a local VAT database. The package doesn’t handle this automatically, so wrap the `Vies` call in a try-catch block or use Laravel’s queue system to retry failed requests.
- Does dragonbe/vies store any data locally, violating GDPR?
- No, the package only interacts with the official VIES SOAP service and doesn’t persist data. GDPR compliance is maintained as long as you only store the VAT ID, validation timestamp, and result in your database—no additional PII. Encrypt VAT numbers in transit/storage for extra security.
- How can I test dragonbe/vies in Laravel?
- Use Laravel’s `Http::fake()` to mock the VIES SOAP response in unit tests. For integration tests, configure the `Vies` class to use a test SOAP endpoint or stub the HTTP client. Test edge cases like invalid VAT numbers, CY formats, and API failures to ensure robustness.
- What alternatives exist for VAT validation in Laravel?
- Alternatives include paid services like Avalara or Taxamo, or PHP packages like `spatie/vat` (for static validation). However, `dragonbe/vies` is the only package offering real-time, official VIES API integration, which is legally required for EU compliance. Weigh cost vs. accuracy needs.
- How do I integrate dragonbe/vies with Laravel’s queue system?
- Dispatch a job (e.g., `VatValidationJob`) that instantiates the `Vies` class and processes the response. This helps manage rate limits and retry failed requests. Use Laravel’s `queue:work` command to handle validation asynchronously during checkout or invoicing.
- What should I do if the VIES API is down or unresponsive?
- Implement a fallback mechanism, such as caching valid responses or using a local VAT database (e.g., `league/geotools`). Log failures and notify admins via Laravel’s notifications system. For critical systems, consider a hybrid approach: validate offline first, then sync with VIES later.