Laravel Dadata Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require icekristal/laravel-dadata
   

2. Publish Config:

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

3. Configure .env:

   DADATA_TOKEN="your_token_here"
   DADATA_SECRET="your_secret_here"
   DADATA_TIMEOUT=10
   

First Use Case: Address Standardization

use Icekristal\DaData\Facades\DaDataAddress;

// Standardize an address
$standardizedAddress = DaDataAddress::standardization('мск сухонска 11/-89');
dd($standardizedAddress);

Key Facades to Know

• DaDataAddress: For address-related operations (standardization, suggestions, geocoding).
• DaDataName: For name parsing and suggestions (e.g., FIO).
• DaDataEmail: For email validation and suggestions.
• DaDataPhone: For phone number validation.
• DaDataCompany: For company lookup (e.g., by INN).
• DaDataBank: For bank identification (e.g., by BIC/SWIFT).
• DaDataPassport: For passport validation (e.g., MVD registry checks).

Implementation Patterns

1. Form Validation & Autocomplete

Use Case: Enhance user input fields (e.g., address, name, email) with real-time suggestions and validation.

Workflow:

1. Frontend: Trigger API calls on input events (e.g., using Laravel Mix/Vue/React).
2. Backend: Use DaDataAddress::suggestions() or DaDataName::suggestions() to fetch hints.
3. Response: Return structured data for dropdowns or tooltips.

Example: Address Suggestions

use Icekristal\DaData\Facades\DaDataAddress;

// Fetch suggestions for an address query
$suggestions = DaDataAddress::suggestions('мск сухонска');
return response()->json($suggestions);

Integration Tip:

• Cache responses (e.g., Cache::remember) for high-frequency queries like autocomplete.
• Use Laravel's FormRequest to validate inputs against DaData responses.

2. Data Cleaning Pipeline

Use Case: Normalize user-submitted data (e.g., addresses, emails) before storage.

Workflow:

1. Standardize Addresses:

   $cleanAddress = DaDataAddress::standardization($rawAddress)->first();
   $user->address = $cleanAddress['result'];
   

2. Validate Emails:

   $validEmail = DaDataEmail::check($rawEmail)->isValid();
   

3. Parse Names:

   $parsedName = DaDataName::parse($rawName);
   $user->first_name = $parsedName['first_name'];
   

Integration Tip:

• Use Laravel's Observers or Model Events to auto-clean data on creating/updating.
• Example observer for User model:

  public function saving(User $user)
  {
      if ($user->isDirty('address')) {
          $cleanAddress = DaDataAddress::standardization($user->address)->first();
          $user->address = $cleanAddress['result'];
      }
  }
  

3. Geocoding for Maps

Use Case: Convert addresses to coordinates for Google Maps or custom maps.

Workflow:

$addressData = DaDataAddress::standardization('мск сухонска 11/-89')->first();
$lat = $addressData['geo_lat'];
$lon = $addressData['geo_lon'];

// Store in database or pass to frontend

Integration Tip:

• Store geo_lat/geo_lon in a morphTo relationship for polymorphic geocoding.
• Use Laravel Scout for full-text search + geospatial queries.

4. Batch Processing

Use Case: Clean existing data in bulk (e.g., migrate old addresses).

Workflow:

use Icekristal\DaData\Facades\DaDataAddress;

$users = User::whereNull('clean_address')->chunk(50, function ($users) {
    foreach ($users as $user) {
        $cleanAddress = DaDataAddress::standardization($user->address)->first();
        $user->update(['clean_address' => $cleanAddress['result']]);
    }
});

Integration Tip:

• Use Laravel Queues (dispatch()) for long-running batches.
• Log failures with try-catch and retry logic.

5. API Proxy Layer

Use Case: Abstract DaData calls behind a service layer for easier testing/mocking.

Example Service:

class DaDataService {
    public function standardizeAddress(string $address): array
    {
        return DaDataAddress::standardization($address)->first();
    }

    public function getAddressSuggestions(string $query): array
    {
        return DaDataAddress::suggestions($query);
    }
}

Integration Tip:

• Use Laravel's bindings to resolve the service in controllers:

  public function __construct(private DaDataService $daData) {}
  

Gotchas and Tips

1. Rate Limiting & Quotas

• Gotcha: DaData has API limits (e.g., 1000 requests/day for free tier).
  • Tip: Implement a throttle middleware or cache responses aggressively.
  • Example:

    Cache::remember("dadata_{$query}", now()->addHours(1), function() use ($query) {
        return DaDataAddress::suggestions($query);
    });
    

2. Error Handling

• Gotcha: DaData may return 429 (Too Many Requests) or 401 (Invalid Token).
  • Tip: Wrap calls in a try-catch and retry with exponential backoff.
  • Example:

    try {
        $result = DaDataAddress::standardization($address);
    } catch (\GuzzleHttp\Exception\RequestException $e) {
        if ($e->getCode() === 429) {
            sleep(2); // Retry after delay
            return $this->standardizeAddress($address);
        }
        throw $e;
    }
    

3. Timeouts

• Gotcha: Slow responses may hit DADATA_TIMEOUT (default: 10s).
  • Tip: Increase timeout in .env for complex queries:

    DADATA_TIMEOUT=30
    

4. Data Quality Flags

• Gotcha: DaData returns qc (quality control) flags (e.g., qc_house: 2 means "house number is uncertain").
  • Tip: Validate flags before trusting data:

    $address = DaDataAddress::standardization($rawAddress)->first();
    if ($address['qc_house'] > 0) {
        // Handle uncertainty (e.g., prompt user for verification)
    }
    

5. Localization

• Gotcha: DaData works best with Russian addresses/names. Non-Russian inputs may return poor results.
  • Tip: Pre-process inputs (e.g., transliterate Cyrillic to Latin) or document limitations.

6. Testing

• Gotcha: DaData API calls are external and flaky in tests.
  • Tip: Mock the facade using Laravel's MockFacade:

    DaDataAddress::shouldReceive('standardization')
        ->once()
        ->andReturn([['result' => 'Test Address']]);
    

7. Configuration Quirks

• Gotcha: The package expects both DADATA_TOKEN and DADATA_SECRET in .env.
  • Tip: If using a single API key, set DADATA_SECRET to the same value as DADATA_TOKEN.

8. Extension Points

• Custom Responses: Extend the package by publishing and modifying the config:

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

  • Override default HTTP client settings (e.g., add headers) in config/dadata.php.

• New Endpoints: Use the underlying Guzzle client to call unsupported DaData APIs:

  $client = app('dadata.client');
  $response = $client->request('POST', '/api/v1/cleanse/phone', [
      'json' => ['phone' => '+79123456789']
  ]);
  

9. Performance

• Gotcha: Parallel requests (e.g., validating 100 emails) may hit rate limits.
  • Tip: Use Laravel's parallel helper or queues to batch requests:

    $emails = User::pluck('email');
    $results =