Laravel Dadata Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require forest-lynx/laravel-dadata
   

   Publish the config file:

   php artisan vendor:publish --provider="ForestLynx\LaravelDadata\DadataServiceProvider" --tag="config"
   

2. Configuration Edit .env with your DaData API key:

   DADATA_API_KEY=your_api_key_here
   DADATA_API_SECRET=your_api_secret_here
   

3. First Use Case Resolve an address via the facade:

   use ForestLynx\LaravelDadata\Facades\Dadata;
   
   $result = Dadata::address()->suggest('ул. Ленина, д. 1, Москва');
   

Implementation Patterns

Core Workflows

1. Suggestions (Autocomplete)

   // Address suggestions
   $suggestions = Dadata::address()->suggest('ул. Ленина', 5); // Limit 5 results
   
   // Company suggestions
   $companies = Dadata::company()->suggest('ООО', 3);
   

2. Validation & Parsing

   // Validate address
   $isValid = Dadata::address()->validate('ул. Ленина, д. 1, Москва');
   
   // Parse address into structured data
   $parsed = Dadata::address()->parse('ул. Ленина, д. 1, Москва');
   

3. Batch Processing

   $batch = Dadata::address()->batch([
       'ул. Ленина, д. 1, Москва',
       'пр. Мира, д. 2, Санкт-Петербург'
   ]);
   

Integration Tips

• Form Handling: Use suggest() in frontend autocomplete inputs (e.g., with Alpine.js or Livewire).
• Model Casting: Cast address fields to DadataAddress for automatic parsing:

  use ForestLynx\LaravelDadata\Casts\DadataAddress;
  
  class User extends Model {
      protected $casts = [
          'address' => DadataAddress::class,
      ];
  }
  

• API Wrappers: Extend the facade for domain-specific logic:

  class CustomDadata extends \ForestLynx\LaravelDadata\Facades\Dadata {
      public function findByQuery($query) {
          return $this->address()->suggest($query, 10)->map(fn($item) => [
              'value' => $item->value,
              'data' => $item->data,
          ]);
      }
  }
  

Gotchas and Tips

Pitfalls

1. Rate Limits

   • DaData enforces strict rate limits. Cache responses aggressively:

     $cached = Cache::remember("dadata_{$query}", now()->addHours(1), fn() =>
         Dadata::address()->suggest($query)
     );
     

   • Monitor usage via the DaData dashboard.

2. API Key Leaks

   • Never expose .env in client-side code. Use backend-only endpoints for DaData calls.

3. Locale Mismatches

   • Ensure the locale in config matches the input data (e.g., ru for Russian addresses). Defaults to ru.

Debugging

• Error Handling: Wrap calls in try-catch:

  try {
      $result = Dadata::address()->suggest('invalid query');
  } catch (\ForestLynx\LaravelDadata\Exceptions\DadataException $e) {
      Log::error('DaData error: ' . $e->getMessage());
      return response()->json(['error' => 'Service unavailable'], 503);
  }
  

• Logging: Enable debug mode in config to log API requests:

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

Extension Points

1. Custom Endpoints Override the base URL in config for private DaData instances:

   DADATA_API_URL=https://your-custom-dadata.ru/api/v1/
   

2. Response Transformers Extend the DadataResponse class to modify parsed data:

   namespace App\Services;
   
   use ForestLynx\LaravelDadata\Responses\DadataResponse;
   
   class CustomDadataResponse extends DadataResponse {
       public function getFormattedAddress() {
           return $this->data['postal_code'] . ' ' . $this->data['region_with_type'];
       }
   }
   

   Bind it in a service provider:

   $this->app->bind(
       \ForestLynx\LaravelDadata\Contracts\DadataResponse::class,
       App\Services\CustomDadataResponse::class
   );
   

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

   Route::post('/dadata-webhook', function (Request $request) {
       $event = $request->json()->all();
       // Process event (e.g., update local DB)
   });