Filament Google Autocomplete Field Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tapp/filament-google-autocomplete-field
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Tapp\FilamentGoogleAutocompleteField\FilamentGoogleAutocompleteFieldServiceProvider"
   

2. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Tapp\FilamentGoogleAutocompleteField\FilamentGoogleAutocompleteFieldPlugin::make(),
           ]);
   }
   

3. First Use Case Add to a Filament form/resource:

   use Tapp\FilamentGoogleAutocompleteField\Fields\GoogleAutocompleteField;
   
   GoogleAutocompleteField::make('address')
       ->apiKey(config('services.google.api_key'))
       ->language('en')
       ->country('us')
   

Implementation Patterns

Common Workflows

1. Basic Integration Use in a Filament Form or Table column:

   GoogleAutocompleteField::make('location')
       ->required()
       ->rules(['required', 'string'])
       ->columnSpanFull()
   

2. Customizing Fields Extract specific address components:

   GoogleAutocompleteField::make('full_address')
       ->fields([
           'street_number',
           'route',
           'locality',
           'administrative_area_level_1',
           'country',
           'postal_code',
       ])
   

3. Dynamic API Key Fetch from .env or a config file:

   GoogleAutocompleteField::make('address')
       ->apiKey(env('GOOGLE_MAPS_API_KEY'))
   

4. Validation & Storage Validate and store formatted address:

   ->afterStateUpdated(function (string $state, GoogleAutocompleteField $field) {
       $this->saveFormattedAddress($state);
   })
   

5. Table Column Display Show formatted address in a table:

   use Tapp\FilamentGoogleAutocompleteField\Columns\GoogleAutocompleteColumn;
   
   GoogleAutocompleteColumn::make('address')
       ->formatStateUsing(fn ($state) => $state['formatted_address'])
   

Integration Tips

• API Key Management Store keys in config/services.php or environment variables. Example:

  'google' => [
      'api_key' => env('GOOGLE_MAPS_API_KEY'),
  ],
  

• Caching Responses Cache API responses to reduce calls:

  ->useCache(true)
  ->cacheDuration(now()->addHours(1))
  

• Localization Set language/country dynamically:

  ->language($user->preferredLanguage())
  ->country($user->countryCode())
  

• Error Handling Handle API errors gracefully:

  ->onError(function (GoogleAutocompleteField $field, $error) {
      $field->addError($error);
  })
  

Gotchas and Tips

Pitfalls

1. API Key Restrictions

   • Ensure your Google Cloud project has the Places API enabled.
   • Avoid hardcoding keys; use environment variables or config files.

2. Rate Limits

   • Google Places API has usage limits.
   • Monitor usage via Google Cloud Console to avoid overages.

3. Field Validation

   • The field returns an array by default. Validate the structure:

     ->rules(['required', 'array', 'min:1'])
     

4. CORS Issues

   • If using in a SPA, ensure your backend CORS policy allows requests to Google’s API.

5. Deprecated Methods

   • Check the changelog for breaking changes between versions.

Debugging

1. API Response Logging Enable debug mode to log API responses:

   ->debug(true)
   

2. Network Tab Inspection Use browser dev tools to inspect failed requests (check for CORS or 403 errors).

3. State Handling The field returns raw Google Places data. Format it before saving:

   ->formatStateUsing(fn ($state) => $state['formatted_address'] ?? null)
   

Extension Points

1. Custom Components Extend the field’s Blade view:

   ->bladeView('custom.google-autocomplete')
   

2. API Response Transformation Modify the response before it’s stored:

   ->transformResponseUsing(function ($response) {
       return collect($response)->only(['formatted_address', 'geometry']);
   })
   

3. Event Listeners Listen to autocomplete events:

   GoogleAutocompleteField::make('address')
       ->listenForEvents([
           'autocomplete.suggestion' => function ($suggestion) {
               // Handle suggestion
           },
       ])
   

4. Testing Mock API responses in tests:

   $this->partialMock(
       \SachinAgarwal1337\GooglePlacesApi\GooglePlacesApi::class,
       ['autocomplete']
   );
   

Pro Tips

• Batch Processing Use the field in bulk actions (e.g., import tools) with caution—rate limits apply per API key.

• Fallback for Offline Provide a fallback input if the API fails:

  ->fallbackTextInput()
  

• Geocoding Integration Combine with tapp/filament-google-maps for map visualization:

  GoogleMapsField::make('map')
      ->latitude($address['geometry']['location']['lat'])
      ->longitude($address['geometry']['location']['lng'])