Laravel Maps Laravel Package

Getting Started

1. Install the package via Composer: composer require larswiegers/laravel-maps.
2. Immediately start using the Blade components—no service provider registration needed.
3. For basic maps, simply drop in <x-maps-leaflet /> or <x-maps-google :centerPoint="['lat' => ..., 'long' => ...]" /> in your Blade template.
4. For Google Maps, set your API key in .env: MAPS_GOOGLE_MAPS_ACCESS_TOKEN=....
5. For Mapbox tiles with Leaflet, add MAPS_MAPBOX_ACCESS_TOKEN=... in .env.
6. If customization is required, publish views: php artisan vendor:publish --provider="Larswiegers\LaravelMaps\LaravelMapsServiceProvider".

Implementation Patterns

• Server-side data binding: Pass arrays of markers, center points, and zoom levels directly from controllers or Livewire components using Blade’s : prefix for JSON-encoded attributes (e.g., :markers="$markers").
• Leaflet reuse: Use multiple maps on a single page by assigning unique id attributes to each component (<x-maps-leaflet id="store-map" ...>).
• Google Maps advanced features: Leverage :fitToBounds="true" for auto-zooming to fit all markers, :centerToBoundsCenter="true" for mid-point centering, and label/icon/info on markers for rich UI—enabled by Google’s Advanced Markers.
• View customization: Override published Blade views (e.g., resources/views/vendor/laravel-maps/components/leaflet.blade.php) to inject custom CSS, event listeners, or extra JavaScript without forking the package.
• Dynamic tile sources: Switch between OpenStreetMap (default), Mapbox, or custom tile servers by setting MAPS_MAPBOX_ACCESS_TOKEN or passing tileUrl via attributes.

Gotchas and Tips

• Multiple maps on page: Leaflet supports multiple instances; Google Maps does not—ensure only one <x-maps-google> per page to avoid conflicts.
• Double quotes: Escape inner double quotes in Blade attributes with \", e.g., :info="'This is \\\"important\\\"'".
• Version locking: Leaflet versions are upgraded automatically by default—use leafletVersion="1.9.4" to pin versions and avoid breaking changes.
• Attribution requirement: Mapbox mandates attribution—provide :attribution="..." if using custom text or omitting default.
• Livewire caveats: Not officially supported; map initialization breaks across re-renders. Workarounds involve manually reinitializing maps after Livewire.hook('message.processed', ...)—but consider server-side rendering alternatives (e.g., caching static map images).
• Testing: Use ->assertSee('<div id="leaflet-map">') in feature tests to verify rendering, but note current tests only validate HTML output—not client-side behavior.
• API key security: Never commit API keys. Use .env, and ensure Google Maps API has only the Maps JavaScript API enabled (avoid enabling unnecessary APIs to reduce billing risk).