Filament Map Picker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require salemaljebaly/filament-map-picker
   

   No additional configuration is required for basic usage.

2. First Use Case: Add the MapPicker component to a Filament form alongside hidden latitude/longitude fields:

   use SalemAljebaly\FilamentMapPicker\MapPicker;
   
   MapPicker::make('location')
       ->latlngFields('latitude', 'longitude')
       ->searchable();
   

3. Where to Look First:

   • Basic Usage Section in the README for core functionality.
   • Configuration Options in the published config file (config/filament-map-picker.php) for global defaults.
   • Form Component API for method chaining (e.g., ->collapsibleSearch()).

Implementation Patterns

Core Workflow

1. Form Integration: Always pair MapPicker with hidden latitude/longitude fields (non-dehydrated). Example:

   Forms\Components\Hidden::make('latitude')->rules(['nullable', 'numeric']),
   Forms\Components\Hidden::make('longitude')->rules(['nullable', 'numeric']),
   MapPicker::make('location')
       ->latlngFields('latitude', 'longitude')
       ->searchable();
   

2. Dynamic Updates: Use live() for real-time updates (e.g., search-as-you-type):

   MapPicker::make('location')
       ->latlngFields('latitude', 'longitude')
       ->searchable()
       ->live(); // Updates hidden fields on marker drag/search
   

3. Table Integration: For read-only maps in tables, use the MapPicker widget:

   use SalemAljebaly\FilamentMapPicker\Widgets\MapPicker;
   
   MapPicker::make('location')
       ->latlngFields('latitude', 'longitude')
       ->readOnly();
   

Advanced Patterns

• Default Center: Set a default location (e.g., for a specific region):

  MapPicker::make('location')
      ->latlngFields('latitude', 'longitude')
      ->defaultCenter([40.7128, -74.0060]); // New York
  

• Custom Styling: Override Leaflet styles via published config:

  // config/filament-map-picker.php
  'map' => [
      'tileLayer' => 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
      'attribution' => '© OpenStreetMap contributors',
  ],
  

• Localization: Use Filament’s built-in localization with RTL support (no extra config):

  MapPicker::make('location')
      ->searchable()
      ->direction('rtl'); // Auto-detected via `dir="auto"` in search input
  

• Livewire Integration: Ensure cleanup on navigation by leveraging Filament’s SPA-safe design (no manual cleanup needed).

Gotchas and Tips

Common Pitfalls

1. Missing Hidden Fields:

   • Error: latlngFields() throws Undefined array key if hidden fields are missing.
   • Fix: Always include Hidden components for latitude/longitude before MapPicker.

2. Dehydrated Fields:

   • Error: Map data not persisted if hidden fields are dehydrated.
   • Fix: Explicitly mark them as non-dehydrated:

     Hidden::make('latitude')->dehydrated(false),
     

3. API Key Misconceptions:

   • Gotcha: Package uses only OpenStreetMap (no Google/Mapbox keys needed).
   • Tip: If blocked by corporate networks, use a proxy or self-hosted tile server.

4. Dark Mode Quirks:

   • Issue: Map tiles may appear washed out in dark mode.
   • Fix: Customize tileLayer in config to use a dark-compatible provider (e.g., https://{s}.tile.openstreetmap.fr/osmfr/{z}/{x}/{y}.png).

5. Performance:

   • Tip: Disable live() for non-critical maps to reduce OpenStreetMap API calls:

     MapPicker::make('location')->live(false);
     

Debugging Tips

• Console Logs: Enable Leaflet debug logs via config:

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

  Check browser console for errors (e.g., CORS issues with tile servers).

• Marker Placement: If markers don’t appear, verify:

  • Hidden fields (latitude/longitude) are populated.
  • No JavaScript errors in the browser console.

• Search Not Working:

  • Ensure searchable() is called.
  • Check for ad-blockers interfering with OpenStreetMap’s Nominatim service.

Extension Points

1. Custom Tile Layers: Override the default OpenStreetMap layer in config:

   'map' => [
       'tileLayer' => 'https://{s}.tile.thunderforest.com/transport/{z}/{x}/{y}.png',
       'tileLayerOptions' => [
           'attribution' => '© Thunderforest',
           'apiKey' => env('THUNDERFOREST_KEY'), // If required
       ],
   ],
   

2. Event Listeners: Attach custom logic to map events (e.g., moveend):

   MapPicker::make('location')
       ->latlngFields('latitude', 'longitude')
       ->extraAttributes([
           'data-filament-map-picker-options' => json_encode([
               'events' => [
                   'moveend' => 'console.log("Map moved!")',
               ],
           ]),
       ]);
   

3. Local Storage: Persist user preferences (e.g., default zoom) using Filament’s useState:

   use Filament\Forms\Components\Hidden;
   
   Hidden::make('default_zoom')
       ->default(fn () => session('map_default_zoom', 13))
       ->afterStateUpdated(fn ($state) => session(['map_default_zoom' => $state]));
   

4. Testing: Mock the map component in PHPUnit:

   $this->filament->mockMapPicker();