Laravel Evatr Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require amondi-media/laravel-evatr
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="AmondiMedia\Evatr\EvatrServiceProvider"
   

2. First Use Case Validate a German VAT number (e.g., DE123456789) in a Laravel controller:

   use AmondiMedia\Evatr\Facades\Evatr;
   
   $isValid = Evatr::validate('DE123456789');
   

3. Key Config Check .env for required settings (e.g., EVATR_API_KEY if the package uses one) and update config/evatr.php if needed.

Implementation Patterns

Core Workflows

1. Validation in Forms Use the facade in Form Requests or controllers:

   public function validateVat(Request $request)
   {
       $vatNumber = $request->vat_number;
       $result = Evatr::validate($vatNumber);
   
       return response()->json($result);
   }
   

2. Batch Validation Validate multiple VAT numbers (if supported):

   $vatNumbers = ['DE123456789', 'FR987654321'];
   $results = Evatr::validateBatch($vatNumbers); // Hypothetical method
   

3. Integration with Eloquent Add a custom accessor to a Company model:

   public function getIsVatValidAttribute()
   {
       return Evatr::validate($this->vat_number);
   }
   

4. API Response Handling Parse the response (e.g., for EU-wide validation):

   $response = Evatr::validate('IT123456789012');
   if ($response['valid']) {
       // Proceed with business logic
   }
   

Advanced Patterns

• Caching Responses Cache validation results to reduce API calls:

  $cacheKey = 'vat_validation_' . md5($vatNumber);
  $result = Cache::remember($cacheKey, now()->addHours(1), function() use ($vatNumber) {
      return Evatr::validate($vatNumber);
  });
  

• Custom Error Handling Extend the package’s exception handling:

  try {
      $result = Evatr::validate($vatNumber);
  } catch (\AmondiMedia\Evatr\Exceptions\ValidationException $e) {
      return back()->withErrors(['vat_number' => $e->getMessage()]);
  }
  

• Testing Mock the facade in PHPUnit:

  $this->mock(\AmondiMedia\Evatr\Facades\Evatr::class)
       ->shouldReceive('validate')
       ->once()
       ->andReturn(['valid' => true]);
  

Gotchas and Tips

Pitfalls

1. Rate Limiting The official German API may throttle requests. Implement retries with exponential backoff:

   use Illuminate\Support\Facades\Http;
   
   Http::retry(3, 100)->get($endpoint);
   

2. Country-Specific Quirks

   • German VAT numbers (DE) require strict formatting (e.g., DE123456789).
   • EU VAT numbers may have varying validation rules per country. Test edge cases like:
     • BE0123456789 (Belgium)
     • NL1234567B01 (Netherlands, includes control digit).

3. Offline Mode The package may rely on an external API. Ensure fallback logic for offline scenarios:

   if (app()->environment('local')) {
       // Use a mock or local validation logic
   }
   

4. Deprecation Risks The package is new (last release in 2026). Monitor for breaking changes or API updates from the German tax office.

Debugging

• Enable Logging Add debug logs to config/evatr.php:

  'debug' => env('EVATR_DEBUG', false),
  

  Check storage/logs/laravel.log for API response details.

• Validate API Responses Inspect raw responses for errors:

  $response = Evatr::getRawResponse('DE123456789');
  Log::debug($response);
  

Extension Points

1. Custom Validation Logic Override the default validator:

   Evatr::extend(function ($vatNumber) {
       // Custom logic (e.g., regex checks)
       return ['valid' => true/false, 'message' => '...'];
   });
   

2. Add Metadata Extend the response to include additional fields:

   $result = Evatr::validate($vatNumber);
   $result['company_name'] = $this->fetchCompanyName($vatNumber);
   

3. Webhook Integration Trigger actions on validation results (e.g., update a companies table):

   event(new VatValidated($vatNumber, $result));