Getting Started

Minimal Setup

Installation:

composer require codewithdennis/filament-simple-map
php artisan vendor:publish --tag="filament-simple-map-config"

Add your Google Maps API key to .env:

GOOGLE_MAPS_EMBED_API_KEY=your_api_key_here

First Use Case: Add the map action to a Filament resource or page:

use CodeWithDennis\FilamentSimpleMap\Actions\MapAction;

public static function getActions(): array
{
    return [
        MapAction::make('view_map')
            ->label('View Location')
            ->queryParam('latitude')
            ->queryParam('longitude'),
    ];
}

Where to Look First:
- README.md for basic usage.
- config/filament-simple-map.php for configuration options.
- src/Actions/MapAction.php for customization hooks.

Implementation Patterns

Common Workflows

Basic Map Integration: Use the default action for displaying a single location:

MapAction::make('map')
    ->latitude($record->latitude)
    ->longitude($record->longitude)
    ->zoom(12)
    ->height('400px')

Dynamic Data Binding: Bind map coordinates dynamically (e.g., from a form or API):

MapAction::make('map')
    ->queryParam('lat')
    ->queryParam('lng')
    ->url(fn (Page $page) => $page->getUrl(['lat' => $page->lat, 'lng' => $page->lng]))

Customizing the Map URL: Override the default Google Maps embed URL:

MapAction::make('map')
    ->mapUrl(fn (string $lat, string $lng) => "https://custom-maps-api.com/?lat=$lat&lng=$lng")

Integration with Filament Forms: Combine with a TextInput for manual coordinate entry:

use Filament\Forms\Components\TextInput;

TextInput::make('latitude')
    ->required()
    ->afterStateUpdated(fn (Page $record, $state) => $record->save())
    ->extraAttributes(['data-action' => 'map-action-update']);

Multi-Record Maps: Use in a table action to show locations for multiple records:

Table::make([
    'name',
    'latitude',
    'longitude',
])
->actions([
    MapAction::make('view')
        ->latitude(fn ($record) => $record->latitude)
        ->longitude(fn ($record) => $record->longitude),
]);

Integration Tips

API Key Management: Restrict your Google Maps API key to only allow embed requests from your domain:
```
GOOGLE_MAPS_EMBED_API_KEY=your_key?referer=yourdomain.com
```

Fallback for Missing Coordinates: Handle cases where latitude/longitude are null:

MapAction::make('map')
    ->latitude(fn ($record) => $record->latitude ?? 0)
    ->longitude(fn ($record) => $record->longitude ?? 0)

Responsive Design: Use relative units for height (e.g., '50vh') to adapt to screen size:
```
MapAction::make('map')->height('50vh')
```

Localization: Pass language parameters to the map URL:

MapAction::make('map')
    ->mapUrl(fn ($lat, $lng) => "https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d3022.215!2d$lng!3d$lat!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x0!2z!5e0!3m2!1s$language!2s$country!4v1234567890")

Gotchas and Tips

Pitfalls

API Key Restrictions:
- Issue: Maps may not load if the API key is restricted to HTTP but your app uses HTTPS (or vice versa).
- Fix: Ensure your key allows both protocols or explicitly set the referrer policy.

Coordinate Validation:

Issue: Invalid coordinates (e.g., latitude > 90) will break the map.

Fix: Validate inputs before passing to the action:

use Illuminate\Support\Facades\Validator;

$validator = Validator::make(['lat' => $lat, 'lng' => $lng], [
    'lat' => 'required|numeric|between:-90,90',
    'lng' => 'required|numeric|between:-180,180',
]);

Caching:

Issue: Google Maps embeds may be cached aggressively, causing stale data.

Fix: Append a timestamp to the URL to bypass cache:

MapAction::make('map')
    ->mapUrl(fn ($lat, $lng) => "https://www.google.com/maps/embed?pb=!1m18!4m12!3m6!1m3!1d3022.215!2d$lng!3d$lat!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!5e0!3m2!1s$language!2s$country!4v" . time())

Iframe Sandboxing:
- Issue: Some browsers block features (e.g., geolocation) in sandboxed iframes.
- Fix: Ensure your API key allows embedding without strict sandboxing:
```
GOOGLE_MAPS_EMBED_API_KEY=your_key?libraries=places&callback=initMap
```
Filament Version Compatibility:
- Issue: The package may not support the latest Filament major version.
- Fix: Check the releases tab for compatibility notes. Use a version constraint in composer.json:
```
"codewithdennis/filament-simple-map": "^1.0"
```

Debugging Tips

Inspect the Embed URL: Open browser dev tools (F12) and check the src attribute of the iframe to verify the URL is correct.
Check API Key Usage: Monitor your Google Cloud Console for API key errors or quota limits.
Disable JavaScript Errors: Temporarily disable JavaScript in your browser to isolate if the issue is client-side:
```
MapAction::make('map')->extraAttributes(['data-disable-js-check' => true])
```

Log Coordinates: Debug coordinate values by logging them in the action:

MapAction::make('map')
    ->latitude(fn ($record) => (log($record->latitude), $record->latitude))
    ->longitude(fn ($record) => (log($record->longitude), $record->longitude))

Extension Points

Custom Map Providers: Extend the action to support non-Google maps (e.g., OpenStreetMap):

MapAction::make('map')
    ->mapUrl(fn ($lat, $lng) => "https://www.openstreetmap.org/?mlat=$lat&mlon=$lng#map=12/$lat/$lng")

Add Markers: Use the extraAttributes method to pass custom JavaScript for markers:

MapAction::make('map')
    ->extraAttributes([
        'data-markers' => json_encode([
            ['lat' => $lat, 'lng' => $lng, 'title' => 'Location']
        ]),
    ])

Then override the default iframe template to include marker logic.

Dynamic Zoom Levels: Adjust zoom based on data (e.g., zoom out for broader regions):
```
MapAction::make('map')
    ->zoom(fn ($record) => $record->is_global ? 2 : 12)
```

Local Storage: Persist map state (e.g., user-selected locations) using localStorage:

MapAction::make('map')
    ->extraAttributes([
        'data-save-to-localstorage' => true,
        'data-storage-key' => 'user_map_prefs',
    ])

Accessibility: Add ARIA labels and keyboard navigation support by extending the Blade template:
```
MapAction::make
```

Filament Simple Map Laravel Package