Laravel Dadata Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sushi-market/laravel-dadata
   php artisan vendor:publish --provider="SushiMarket\DaData\DaDataServiceProvider"
   

   Add these to .env:

   DADATA_TOKEN=your_api_token_here
   DADATA_SECRET=your_secret_key_here
   DADATA_API_KEY=your_api_key_here
   

2. First Use Case: Validate and suggest corrections for a user's address in a form:

   use SushiMarket\DaData\Facades\DaData;
   
   $address = '1600 Amphitheatre Parkway, Mountain View';
   $result = DaData::suggest('address', $address);
   
   // Output corrected address
   dd($result->suggestions[0]->value);
   

3. Key Facade Methods:

   • suggest($type, $query) – Get suggestions for addresses, names, or organizations.
   • clean($type, $query) – Clean and standardize input (e.g., addresses).
   • 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, name) with real-time suggestions.
• Pattern:

  // In a controller or service
  public function autocomplete(Request $request) {
      $query = $request->input('query');
      $type = $request->input('type'); // e.g., 'address', 'name'
  
      $suggestions = DaData::suggest($type, $query)
          ->take(5) // Limit suggestions
          ->pluck('value');
  
      return response()->json($suggestions);
  }
  

• Integration:
  • Attach to a frontend autocomplete library (e.g., Select2, Typeahead.js).
  • Cache responses (e.g., Cache::remember()) to reduce API calls.

2. Data Cleaning Pipeline

• Use Case: Standardize user-submitted data (e.g., addresses) before storage.
• Pattern:

  public function store(Request $request) {
      $data = $request->validate([
          'address' => 'required|string',
      ]);
  
      $cleanedAddress = DaData::clean('address', $data['address']);
      $data['address'] = $cleanedAddress->result;
  
      // Save to database
      User::create($data);
  }
  

• Tip: Chain with Laravel’s after hooks or Observers for global cleaning.

3. Batch Processing

• Use Case: Clean or validate a list of records (e.g., CSV imports).
• Pattern:

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

• Optimization: Use Laravel Queues (dispatch()) for long-running batches.

4. Custom Validation Rules

• Use Case: Add DaData validation to Laravel’s built-in validation.
• Pattern:

  use Illuminate\Validation\Rule;
  
  $rules = [
      'address' => [
          'required',
          Rule::function('dadata_valid_address')
              ->message('Invalid address. Please correct it.'),
      ],
  ];
  
  // In AppServiceProvider::boot()
  Validator::extend('dadata_valid_address', function ($attribute, $value, $parameters, $validator) {
      return DaData::validate('address', $value)->isValid();
  });
  

Integration Tips

1. Rate Limiting:

   • DaData has API limits (e.g., 1000 requests/day for free tier). Implement middleware to throttle requests:

     // app/Http/Middleware/ThrottleDaData.php
     public function handle($request, Closure $next) {
         return $next($request)->throttle('dadata', 1, 1); // 1 request per second
     }
     

2. Error Handling:

   • Wrap DaData calls in try-catch blocks to handle API failures gracefully:

     try {
         $result = DaData::suggest('address', $query);
     } catch (\SushiMarket\DaData\Exceptions\DaDataException $e) {
         Log::error("DaData API error: " . $e->getMessage());
         return back()->withInput()->with('error', 'Service unavailable. Try again later.');
     }
     

3. Localization:

   • DaData supports multiple regions (e.g., address.ru, address.ua). Specify in queries:

     $result = DaData::suggest('address.ru', $query); // Russian addresses
     

4. Testing:

   • Mock the DaData facade in tests:

     $this->mock(SushiMarket\DaData\Facades\DaData::class, function ($mock) {
         $mock->shouldReceive('suggest')
             ->once()
             ->andReturn(new \SushiMarket\DaData\Responses\SuggestResponse([...]));
     });
     

Gotchas and Tips

Pitfalls

1. Token Management:

   • Issue: Hardcoding DADATA_TOKEN in .env exposes it in version control if not added to .gitignore.
   • Fix: Use Laravel’s environment variables and restrict access to .env:

     echo ".env" >> .gitignore
     

2. API Quotas:

   • Issue: Exceeding DaData’s free tier limits (e.g., 1000 requests/day) will return 429 Too Many Requests.
   • Fix:
     • Monitor usage via DaData Dashboard.
     • Implement exponential backoff in retries:

       use Symfony\Component\HttpClient\RetryStrategy;
       
       $client = Http::withOptions([
           'retry' => RetryStrategy::fromCalls(3, function ($retries, $response) {
               return $response->getStatusCode() === 429;
           }),
       ]);
       

3. Response Parsing:

   • Issue: DaData’s response structure may change (e.g., nested suggestions array). Break if not handled dynamically.
   • Fix: Use Laravel Collections for flexible access:

     $suggestions = collect($result->suggestions)->pluck('value');
     

4. Character Encoding:

   • Issue: Cyrillic or special characters in queries may cause encoding issues.
   • Fix: Ensure UTF-8 encoding in requests:

     $query = mb_convert_encoding($query, 'UTF-8');
     

Debugging Tips

1. Log Raw Responses:

   • Enable debug mode to log API responses:

     DADATA_DEBUG=true
     

   • Check logs in storage/logs/laravel.log.

2. Validate API Keys:

   • Test keys manually via DaData API Console before integrating.

3. Common Errors:

   • 401 Unauthorized: Invalid DADATA_TOKEN or DADATA_SECRET.
   • 400 Bad Request: Malformed query (e.g., empty string, unsupported type).
   • 500 Server Error: DaData server-side issue (check status page).

Extension Points

1. Custom Response Handlers:

   • Extend the SushiMarket\DaData\Responses\BaseResponse class to add custom logic:

     class CustomResponse extends BaseResponse {
         public function getFormattedAddress() {
             return $this->result . ', ' . $this->postal_code;
         }
     }
     

2. Add New DaData Services:

   • DaData offers additional services (e.g., bank-resident, phone). Extend the package:

     // app/Providers/DaDataServiceProvider.php
     public function register() {
         $this->app->singleton('dadata.bank-resident', function () {
             return new \SushiMarket\DaData\Services\BankResidentService();
         });
     }
     

3. Webhook Integration:

   • Use DaData’s webhook events to trigger Laravel jobs:

     Route::post('/dadata-webhook', function (Request $request) {
         $event = $request->input('event');
         if ($event === 'address.updated') {
             AddressUpdatedJob::dispatch($request->input('data'));
         }
     });
     

4. Fallback Mechanisms:

   • Implement fallback logic if DaData is unavailable:

     try {
         $result = DaData::suggest('