Laravel Dadata Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require movemoveapp/laravel-dadata
   

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

2. Publish Config:

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

   This generates config/dadata.php with default settings (API key, endpoint, etc.).

3. First Use Case: Validate and suggest corrections for a user's input (e.g., address or name):

   use MoveMoveIo\DaData\Facades\DaData;
   
   $result = DaData::suggest('address', '123 Main St, Moscow'); // Returns suggestions
   $result = DaData::clean('address', '123 Main St, Moscow');    // Returns cleaned data
   

Key Facades

• DaData::suggest($type, $query): Get autocomplete suggestions (e.g., for forms).
• DaData::clean($type, $query): Correct syntax errors in input (e.g., addresses, names).
• DaData::validate($type, $query): Validate input against DaData’s rules.

Implementation Patterns

Common Workflows

1. Form Validation & Autocomplete

• Use Case: Enhance user input fields (e.g., address, phone) with real-time suggestions.
• Implementation:

  // In a controller or service
  public function getAddressSuggestions(Request $request) {
      $query = $request->input('query');
      $suggestions = DaData::suggest('address', $query);
      return response()->json($suggestions);
  }
  

  • Frontend Integration: Use JavaScript (e.g., with axios) to call the endpoint and display suggestions in a dropdown.

2. Data Cleaning on Submission

• Use Case: Automatically correct user-submitted data (e.g., fixing typos in addresses).
• Implementation:

  public function storeUserProfile(Request $request) {
      $request->validate([...]);
  
      $cleanedAddress = DaData::clean('address', $request->address);
      $cleanedPhone   = DaData::clean('phone', $request->phone);
  
      User::create([
          'name'     => $request->name,
          'address'  => $cleanedAddress['result'],
          'phone'    => $cleanedPhone['result'],
      ]);
  }
  

3. Bulk Processing

• Use Case: Clean or validate a batch of records (e.g., during data migration).
• Implementation:

  $users = User::all();
  foreach ($users as $user) {
      $cleanedData = DaData::clean('address', $user->address);
      $user->update(['address' => $cleanedData['result']]);
  }
  

• Tip: Use Laravel’s chunk() for large datasets to avoid memory issues.

4. Customizing API Requests

• Use Case: Override default settings (e.g., custom endpoint, headers).
• Implementation:

  // In config/dadata.php
  'api_key' => env('DADATA_API_KEY'),
  'endpoint' => 'https://cleaner.dadata.ru/api/v1/clean',
  'headers' => [
      'Content-Type' => 'application/json',
      'Accept'       => 'application/json',
  ],
  

  Or dynamically:

  $result = DaData::setOptions(['endpoint' => 'custom-endpoint'])->clean('address', 'query');
  

Integration Tips

Laravel Services

Wrap DaData calls in a service class for reusability:

namespace App\Services;

use MoveMoveIo\DaData\Facades\DaData;

class DaDataService {
    public function cleanAddress(string $address): string {
        $cleaned = DaData::clean('address', $address);
        return $cleaned['result'] ?? $address;
    }
}

Form Requests

Validate and clean data in FormRequest classes:

public function rules() {
    return [
        'address' => 'required|string',
        'phone'   => 'nullable|string',
    ];
}

public function withValidator($validator) {
    $validator->after(function ($validator) {
        $validator->errors()->merge([
            'address' => DaData::validate('address', $this->address) ? '' : 'Invalid address',
        ]);
    });
}

API Rate Limiting

DaData has rate limits. Cache responses to avoid hitting limits:

$cacheKey = "dadata_suggestions_{$query}";
$suggestions = Cache::remember($cacheKey, now()->addMinutes(5), function() use ($query) {
    return DaData::suggest('address', $query);
});

Gotchas and Tips

Pitfalls

1. API Key Management:

   • Never hardcode the API key in config files. Use Laravel’s .env:

     DADATA_API_KEY=your_api_key_here
     

   • Gotcha: If the key is leaked, revoke it immediately in the DaData dashboard.

2. Rate Limits:

   • DaData enforces rate limits. Exceeding limits may return 429 Too Many Requests.
   • Fix: Implement exponential backoff or caching (as shown above).

3. Data Types:

   • DaData supports specific types (e.g., address, phone, name). Using unsupported types (e.g., email) will fail silently or return unexpected results.
   • Tip: Check DaData’s API docs for supported types.

4. Response Handling:

   • The clean and validate methods return arrays with keys like result, qc, and meta. Always check for result:

     $cleaned = DaData::clean('address', 'bad address');
     if (empty($cleaned['result'])) {
         // Handle error (e.g., log or notify user)
     }
     

5. PHP Version Compatibility:

   • The package supports PHP 7.3–8.1. If using PHP 8.1+, ensure your Laravel version is compatible (e.g., Laravel 9.x).

Debugging

1. Enable Guzzle Logging: Add this to config/dadata.php to debug API calls:

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

   Logs will appear in storage/logs/laravel.log.

2. Mocking for Tests: Use Laravel’s HTTP client to mock DaData responses:

   $response = Http::fake([
       'https://cleaner.dadata.ru/api/v1/clean' => Http::response(['result' => 'cleaned address']),
   ]);
   
   $result = DaData::clean('address', 'test');
   $response->assertSent(function ($request) {
       return $request->toDadataApi();
   });
   

3. Common Errors:

   • 401 Unauthorized: Invalid API key. Double-check .env.
   • 400 Bad Request: Invalid query or type. Validate inputs.
   • 500 Server Error: DaData API issue. Check their status page.

Extension Points

1. Custom Types: DaData supports custom types. Extend the package by adding a new facade method:

   // In a service provider
   DaData::extend('custom_type', function ($query) {
       return DaData::callApi('custom_type', $query);
   });
   

2. Webhook Integration: Use DaData’s webhook API to process data in real-time. Create a Laravel route:

   Route::post('/dadata-webhook', [DaDataWebhookController::class, 'handle']);
   

3. Batch Processing: For large datasets, use Laravel’s queue system to process records asynchronously:

   foreach ($users as $user) {
       CleanUserAddress::dispatch($user);
   }
   

   // CleanUserAddress.php
   public function handle() {
       $cleaned = DaData::clean('address', $this->user->address);
       $this->user->update(['address' => $cleaned['result']]);
   }
   

4. Local Testing: Use DaData’s sandbox for testing. Override the endpoint in config:

   'endpoint' => 'https://cleaner.sandbox.dadata.ru/api/v1/clean',