Statamic Algolia Places Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require spatie/statamic-algolia-places
   

   Publish the fieldtype assets (if needed):

   php artisan vendor:publish --provider="Spatie\AlgoliaPlaces\AlgoliaPlacesServiceProvider"
   

2. Register the Fieldtype Add the fieldtype to your Statamic blueprint:

   fields:
       location:
           type: algolia_places
           algolia_app_id: 'YOUR_APP_ID'
           algolia_search_key: 'YOUR_SEARCH_KEY'
   

3. First Use Case Create a content entry with the fieldtype. The dropdown will autocomplete locations via Algolia Places API. The saved data will include structured location details (e.g., name, city, country).

Implementation Patterns

Workflows

1. Content Creation

   • Use the fieldtype in blueprints for location-based entries (e.g., "Event Location," "Store Address").
   • Example blueprint snippet:

     fields:
         venue:
             type: algolia_places
             algolia_app_id: '{{ env("ALGOLIA_APP_ID") }}'
             algolia_search_key: '{{ env("ALGOLIA_SEARCH_KEY") }}'
             instructions: "Select the venue from the autocomplete dropdown."
     

2. Data Retrieval Access the structured location data in templates:

   {{ entry.venue.name }}  {# e.g., "Kruikstraat 22" #}
   {{ entry.venue.city }}, {{ entry.venue.country }}  {# e.g., "Antwerpen, België" #}
   

3. Validation Ensure required fields are set in the blueprint:

   fields:
       address:
           type: algolia_places
           required: true
   

Integration Tips

• Environment Variables Store ALGOLIA_APP_ID and ALGOLIA_SEARCH_KEY in .env for security:

  ALGOLIA_APP_ID=your_app_id
  ALGOLIA_SEARCH_KEY=your_search_key
  

  Reference them in blueprints:

  algolia_app_id: '{{ env("ALGOLIA_APP_ID") }}'
  

• Custom Styling Override the fieldtype’s CSS/JS by publishing assets and extending:

  php artisan vendor:publish --tag=algolia-places-assets --provider="Spatie\AlgoliaPlaces\AlgoliaPlacesServiceProvider"
  

  Modify the published files in resources/js or resources/css.

• Fallback for Offline Add a default value or instructions for when Algolia is unavailable:

  fields:
      location:
          type: algolia_places
          default: { name: "Default Location", city: "City", country: "Country" }
  

Gotchas and Tips

Pitfalls

1. Algolia API Limits

   • Free Algolia Plans have request limits. Monitor usage in the Algolia Dashboard.
   • Cache responses client-side to reduce API calls (e.g., using Laravel’s cache() helper).

2. Fieldtype Not Rendering

   • Cause: Missing algolia_app_id or algolia_search_key in the blueprint.
   • Fix: Verify the keys are correctly set in the blueprint or .env.

3. Data Structure Mismatch

   • The fieldtype returns a nested array. Ensure your templates handle missing keys gracefully:

     {{ entry.location.city ?? 'N/A' }}
     

4. Archived Package

   • The package is archived (no new releases). Test thoroughly in staging before production use.

Debugging

• Console Errors Check browser console for Algolia API errors (e.g., invalid keys, CORS issues). Validate keys in the Algolia Dashboard.

• Network Requests Use browser dev tools to inspect the Algolia Places API calls. Ensure the search endpoint is reachable:

  https://places-algolia.deta.dev/1/places/query?...
  

Extension Points

1. Customize Autocomplete Options Pass additional Algolia Places parameters via the attributes key in the blueprint:

   fields:
       location:
           type: algolia_places
           attributes:
               language: 'en'
               aroundLatLngViaIP: true
   

   See Algolia Places API docs for options.

2. Post-Save Processing Use Statamic’s entry.saving event to transform the location data:

   // In a service provider or listener
   Event::listen(EntrySaving::class, function (EntrySaving $event) {
       $location = $event->entry->location;
       $event->entry->setData('formatted_address', "{$location['name']}, {$location['city']}");
   });
   

3. Fallback to Manual Input Combine with a text fieldtype for manual overrides:

   fields:
       location:
           type: algolia_places
       manual_location:
           type: text
           hidden: true  {# Show only if Algolia fails #}