Laravel Dadata Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require zemlecht/laravel-dadata
   

   For Laravel <5.5, manually register MoveMoveIo\DaData\DaDataServiceProvider in config/app.php.

2. Publish Config:

   php artisan vendor:publish --provider="MoveMoveIo\DaData\DaDataServiceProvider"
   

   This generates .env keys (DADATA_TOKEN, DADATA_SECRET) and config/dadata.php.

3. Configure .env:

   DADATA_TOKEN=your_api_token
   DADATA_SECRET=your_api_secret
   

4. First Use Case: Validate and suggest corrections for a phone number:

   use MoveMoveIo\DaData\Facades\DaData;
   
   $phone = DaData::phone()->validate('+7(903)123-45-67');
   // Returns corrected phone in E.164 format: "+79031234567"
   

Implementation Patterns

Core Workflows

1. Validation & Correction: Use facades for common fields (phone, address, name):

   // Phone
   $corrected = DaData::phone()->suggest('+7(903)123-45-67');
   
   // Address
   $suggestions = DaData::address()->suggest('ул. Ленина, д. 10');
   
   // Name
   $normalized = DaData::name()->clean('Иван Иванов');
   

2. Batch Processing: Process multiple inputs efficiently:

   $phones = ['+7(903)123-45-67', '+7(916)789-01-23'];
   $results = DaData::phone()->batch($phones);
   

3. Integration with Forms: Use middleware to auto-correct form submissions:

   // In FormRequest
   public function passedValidation()
   {
       $this->merge([
           'phone' => DaData::phone()->validate($this->phone),
       ]);
   }
   

4. Caching Responses: Cache frequent queries (e.g., address suggestions) to reduce API calls:

   $suggestions = Cache::remember("dadata_address_{$query}", now()->addHours(1), function() use ($query) {
       return DaData::address()->suggest($query);
   });
   

Integration Tips

1. Laravel Validation: Extend validation rules:

   use MoveMoveIo\DaData\Rules\ValidPhone;
   
   $request->validate([
       'phone' => ['required', new ValidPhone],
   ]);
   

2. API Rate Limiting: Monitor API usage via config/dadata.php:

   'rate_limit' => 100, // Max requests per minute
   

3. Error Handling: Wrap API calls in try-catch:

   try {
       $result = DaData::phone()->validate($input);
   } catch (\MoveMoveIo\DaData\Exceptions\DaDataException $e) {
       report($e);
       return back()->withError('DaData service unavailable.');
   }
   

4. Testing: Use mocks in PHPUnit:

   $this->mock(DaData::class)->shouldReceive('phone')->andReturnSelf()
       ->shouldReceive('validate')->andReturn('+79031234567');
   

Gotchas and Tips

Pitfalls

1. Token/Secret Mismatch:

   • Ensure DADATA_TOKEN and DADATA_SECRET match your DaData account.
   • Debug: Check config/dadata.php for typos in keys.

2. Rate Limits:

   • Default limit: 100 requests/minute. Exceeding this returns 429 Too Many Requests.
   • Fix: Implement exponential backoff or cache responses aggressively.

3. Character Encoding:

   • DaData expects UTF-8. Non-UTF-8 inputs (e.g., from legacy databases) may fail.
   • Fix: Normalize strings:

     $cleanInput = mb_convert_encoding($input, 'UTF-8');
     

4. Phone Format Quirks:

   • Inputs like 8(903)123-45-67 (missing + or 7) may not validate.
   • Fix: Prepend +7 or use DaData::phone()->clean() first.

5. Address Suggestions:

   • Partial matches (e.g., ул. Л) return fewer results. Use full addresses for accuracy.

Debugging

1. Enable Logging: Set debug: true in config/dadata.php to log raw API responses:

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

2. API Response Inspection: Use ->raw() to inspect unprocessed responses:

   $raw = DaData::phone()->raw()->validate($phone);
   

3. Common HTTP Errors:

   • 401 Unauthorized: Invalid token/secret.
   • 403 Forbidden: IP blocked or quota exceeded.
   • 500 Server Error: DaData service issue (check status page).

Extension Points

1. Custom Endpoints: Extend the SDK for unsupported fields (e.g., email):

   // In app/Providers/DaDataServiceProvider.php
   $this->app->extend('dadata', function ($dadata) {
       $dadata->email = new EmailService($dadata->client);
       return $dadata;
   });
   

2. Webhook Integration: Use DaData’s webhook events to sync corrections in real-time:

   Route::post('/dadata-webhook', function (Request $request) {
       // Process webhook payload
   });
   

3. Local Testing: Mock the DaData client for CI/CD:

   // In tests/CreatesApplication.php
   $this->app->instance(\MoveMoveIo\DaData\DaDataClient::class, new MockClient());
   

4. Queue Delayed Requests: Offload heavy corrections to queues:

   DaData::phone()->later()->validate($phone); // Uses queue