Filament Map Picker Laravel Package

Technical Evaluation

Architecture Fit

• Filament v5 Native Integration: The package is purpose-built for Filament v5, leveraging its form component ecosystem. This ensures seamless integration with existing Filament-based admin panels, reducing architectural friction.
• Leaflet/OpenStreetMap Stack: Uses open-source, lightweight libraries (Leaflet + OpenStreetMap) for map functionality, avoiding vendor lock-in or paid API dependencies. This aligns well with cost-sensitive or privacy-focused applications.
• SPA/Livewire Compatibility: Designed to work with Filament’s Livewire backend and SPA-friendly cleanup, making it suitable for modern Laravel applications with dynamic UX requirements.

Integration Feasibility

• Low Barrier to Entry: Minimal setup (single Composer dependency + optional config publish) with no API keys required. Ideal for rapid prototyping or adding geolocation to forms.
• Form-Centric Design: Tightly coupled with Filament’s form system, requiring only hidden latitude/longitude fields for persistence. This simplifies database schema changes.
• Theme Agnostic: Supports dark/light modes and RTL, reducing UI customization overhead for multilingual or themed applications.

Technical Risk

• Dependency Maturity: Package has 2 stars and a recent release (2026-02-06) but lacks active community engagement (0 dependents). Risk of unaddressed bugs or lack of long-term maintenance.
• OpenStreetMap Limitations: Relies on free-tier OpenStreetMap, which may have:
  • Rate limits or usage restrictions for high-traffic apps.
  • Less polished UI than paid alternatives (e.g., Mapbox).
• No Advanced Features: Absence of drawing tools (e.g., polygons) or GeoJSON support may limit use cases requiring spatial data manipulation.
• Filament v5 Lock-in: Tied to Filament’s form lifecycle; migration to other frameworks (e.g., Livewire standalone) would require refactoring.

Key Questions

1. Use Case Alignment:
   • Is the package’s search-focused, non-drawing approach sufficient for your geolocation needs?
   • Do you require paid provider features (e.g., Mapbox’s advanced layers) or custom markers/clusters?
2. Scalability:
   • Will OpenStreetMap’s free tier support your expected user load (e.g., concurrent map searches)?
   • Are there fallback mechanisms for OpenStreetMap downtime?
3. Maintenance:
   • How will you handle package abandonment? Are there internal resources to fork/maintain it?
   • Does your team have experience with Leaflet customization for edge cases (e.g., mobile UX)?
4. Data Model:
   • Are latitude/longitude fields already in your schema, or will this require migrations?
   • How will you handle legacy data (e.g., existing address fields) during adoption?
5. Alternatives:
   • Have you evaluated Filament’s built-in map components (if any) or other packages like spatie/laravel-geocoder for broader functionality?

Integration Approach

Stack Fit

• Laravel 11/12 + Filament v5: Native compatibility with no framework conflicts. The package’s design assumes this stack, minimizing cross-cutting concerns.
• Leaflet/OpenStreetMap: Lightweight and compatible with Laravel’s asset pipeline (no heavy JS bundling required). Works alongside existing frontend stacks (e.g., Alpine.js, Tailwind).
• Livewire Integration: Built for Filament’s Livewire backend, ensuring real-time updates without full SPA complexity.

Migration Path

1. Pre-Integration:
   • Add latitude/longitude columns to the target database table (if not present).
   • Ensure Filament v5 is updated (composer require filament/filament:"^5").
2. Installation:

   composer require salemaljebaly/filament-map-picker
   php artisan vendor:publish --tag=filament-map-picker-config  # Optional
   

3. Form Integration:
   • Replace text inputs for addresses with MapPicker in Filament forms.
   • Example:

     MapPicker::make('location')
         ->latlngFields('latitude', 'longitude')
         ->searchable()
         ->collapsibleSearch();
     

4. Testing:
   • Validate map rendering in light/dark modes and RTL locales.
   • Test Livewire navigation (e.g., tab switching) to ensure SPA-safe cleanup.

Compatibility

• Filament Plugins: May conflict with other Filament form components (e.g., custom JS/CSS). Test in a staging environment.
• Custom Themes: The package supports Filament’s theming system, but extensive CSS overrides may require additional styling.
• Mobile Responsiveness: Leaflet is mobile-friendly, but test on target devices for pinch-zoom/gesture interactions.

Sequencing

1. Phase 1: Pilot in a non-critical form (e.g., user profile location) to validate UX and performance.
2. Phase 2: Roll out to high-priority workflows (e.g., venue creation, delivery address forms).
3. Phase 3: Monitor OpenStreetMap usage and implement fallbacks (e.g., caching, rate-limiting) if needed.
4. Phase 4: Extend functionality (e.g., custom markers) via Leaflet plugins if required.

Operational Impact

Maintenance

• Dependency Updates: Monitor for Leaflet/OpenStreetMap updates that may break compatibility. The package’s MIT license allows forks if maintenance stalls.
• Config Management: Optional published config enables customization (e.g., map tiles), but changes require redeployment.
• Logging: No built-in logging; instrument map interactions (e.g., search failures) via Filament’s logging system.

Support

• Community: Limited (2 stars, no dependents). Support relies on:
  • GitHub issues (response time unknown).
  • Leaflet/OpenStreetMap documentation for troubleshooting.
• Internal Resources: Assign a technical owner to handle edge cases (e.g., custom Leaflet plugins).
• Fallback Plan: Document steps to switch to a paid provider (e.g., Mapbox) if OpenStreetMap limitations arise.

Scaling

• Performance:
  • OpenStreetMap’s free tier may throttle requests under heavy load. Test with load testing tools (e.g., k6).
  • Consider caching map tiles or proxying requests for high-traffic apps.
• Database: latitude/longitude fields are lightweight, but ensure your DB can handle geospatial queries (e.g., distance calculations) if needed.
• Concurrency: Leaflet is single-page focused; ensure Filament’s Livewire backend can handle simultaneous map sessions.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1–2 hours: Install and test basic usage.
  • 4–8 hours: Customize appearance (themes, markers) and handle edge cases (e.g., invalid coordinates).
• End-User Training:
  • Minimal training needed; UX mimics familiar map interfaces.
  • Highlight features like search suggestions and my-location in tooltips/help text.
• Documentation Gaps:
  • The README is succinct but lacks advanced use cases (e.g., custom events).
  • Create internal runbooks for:
    • Troubleshooting map loading.
    • Integrating with geocoding services (e.g., reverse geocoding).