Filament Map Field Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require lbcdev/filament-map-field
   

   Publish config (if needed):

   php artisan vendor:publish --provider="Lbcdev\FilamentMapField\FilamentMapFieldServiceProvider" --tag="config"
   

2. First Use Case Add a map field to a Filament form:

   use Lbcdev\FilamentMapField\Forms\Components\MapField;
   
   MapField::make('coordinates')
       ->label('Location')
       ->columnSpanFull()
       ->required()
       ->default([
           'lat' => 40.7128, // Default latitude
           'lng' => -74.0060, // Default longitude
       ]);
   

3. Where to Look First

   • Documentation: Check the GitHub README for basic usage examples.
   • Source: Review src/Forms/Components/ and src/Resources/ViewComponents/ for customization hooks.
   • Config: config/filament-map-field.php for global settings (e.g., default map provider).

Implementation Patterns

Common Workflows

1. Basic Form Integration

// For a single coordinate field (lat/lng stored as separate columns)
MapField::make('location')
    ->latColumn('latitude')
    ->lngColumn('longitude')
    ->mapOptions([
        'zoom' => 12,
        'center' => [40.7128, -74.0060],
    ]);

2. JSON-Stored Coordinates (v1.1.0+)

// Store coordinates in a JSON column (e.g., `location` column)
MapField::make('location')
    ->jsonColumn('location')
    ->default(['lat' => 34.0522, 'lng' => -118.2437]);

3. MapBounds for Area Selection

use Lbcdev\FilamentMapField\Forms\Components\MapBoundsField;

MapBoundsField::make('search_area')
    ->northEastColumn('northeast')
    ->southWestColumn('southwest')
    ->mapOptions(['zoom' => 8]);

4. Infolist Display

use Lbcdev\FilamentMapField\Resources\ViewComponents\MapEntry;

MapEntry::make('coordinates')
    ->latColumn('latitude')
    ->lngColumn('longitude')
    ->openInNewTab()
    ->mapOptions(['zoom' => 15]);

5. Dynamic Defaults

Use a closure for dynamic defaults (e.g., user's current location):

MapField::make('address')
    ->default(fn () => [
        'lat' => request()->user()->last_latitude ?? 40.7128,
        'lng' => request()->user()->last_longitude ?? -74.0060,
    ]);

Integration Tips

With Laravel Models

Ensure your model has the correct columns:

// For separate lat/lng columns
protected $fillable = ['latitude', 'longitude'];

// For JSON storage
protected $casts = [
    'location' => 'array',
];

Validation

Add validation rules to your form:

->rules([
    'coordinates.lat' => 'required|numeric|between:-90,90',
    'coordinates.lng' => 'required|numeric|between:-180,180',
]);

Custom Map Providers

Override the default provider (e.g., switch from OpenStreetMap to Google Maps):

MapField::make('map')
    ->mapOptions([
        'provider' => 'google',
        'apiKey' => config('services.google_maps.api_key'),
    ]);

Localization

Translate labels and placeholders:

->label(__('Location'))
->placeholder(__('Search for a location...'));

Conditional Rendering

Show/hide the map based on other fields:

->visible(fn ($record) => $record->is_premium_user)

Gotchas and Tips

Pitfalls

1. Column Mismatch Errors

• Issue: Undefined column errors when using latColumn()/lngColumn().
• Fix: Ensure your model/table has the specified columns. For JSON storage, use jsonColumn() instead.

2. Default Values Not Persisting

• Issue: Default values not saving to the database.
• Fix: Ensure the field is included in $fillable (for separate columns) or properly cast (for JSON). Example:

  // Model
  protected $fillable = ['coordinates'];
  protected $casts = ['coordinates' => 'array'];
  

3. Map Not Loading

• Issue: Blank map or API errors.
• Fix:
  • Check your internet connection (maps rely on external APIs).
  • Verify mapOptions includes a valid provider (e.g., 'provider' => 'openstreetmap').
  • Ensure API keys are correct (for providers like Google Maps).

4. JSON Path Issues (v1.1.0+)

• Issue: Undefined index when using dot notation (e.g., 'location.lat').
• Fix: Use the exact column name specified in jsonColumn(). Example:

  // Correct: Column is `location` (JSON), and you access `location.lat`
  MapField::make('location')
      ->jsonColumn('location')
      ->latPath('lat') // Explicitly define paths
      ->lngPath('lng');
  

5. Filament v3 vs. v4

• Issue: Component not rendering in Filament v4.
• Fix: The package supports both, but ensure you’re using the correct namespace:

  // Filament v4
  use Lbcdev\FilamentMapField\Forms\Components\MapField;
  

Debugging Tips

Log Map Options

Add this to your mapOptions to debug:

->mapOptions([
    'debug' => true, // Logs options to Laravel logs
    'zoom' => 10,
]);

Check Livewire Component

The package wraps lbcdev-map. If issues persist:

• Review the underlying Livewire component’s docs.
• Check browser console for Livewire errors (e.g., wire:ignore misconfigurations).

Clear Cache

After installing or updating:

php artisan optimize:clear
php artisan view:clear

Extension Points

Custom Map Markers

Override the default marker icon:

->mapOptions([
    'markerIcon' => 'https://example.com/custom-marker.png',
]);

Custom Styling

Use Filament’s CSS utilities or inline styles:

->columnSpan('full')
->extraAttributes(['style' => 'height: 400px;']);

Event Listeners

Listen for coordinate changes:

->extraAttributes(['wire:ignore' => 'false'])
->mapOptions([
    'events' => [
        'moveend' => 'updateCoordinates',
    ],
])
->script(<<<'JS'
    document.addEventListener('livewire:init', () => {
        Livewire.on('updateCoordinates', (coords) => {
            @this.set('coordinates', coords);
        });
    });
JS);

Custom Providers

Extend the package to support additional map providers:

1. Create a new service provider:

   namespace App\Providers;
   
   use Lbcdev\FilamentMapField\Contracts\MapProvider;
   use Illuminate\Support\ServiceProvider;
   
   class CustomMapProviderServiceProvider extends ServiceProvider
   {
       public function register()
       {
           $this->app->bind(MapProvider::class, function () {
               return new class implements MapProvider {
                   public function getScript(): string
                   {
                       return '<script src="https://custom-maps.com/script.js"></script>';
                   }
               };
           });
       }
   }
   

2. Register the provider in config/app.php.

Override Views

Publish and modify the package’s views:

php artisan vendor:publish --tag="filament-map-field-views"

Edit files in resources/views/vendor/filament-map-field/.