Filament Map Picker Laravel Package

Technical Evaluation

Architecture Fit

• Filament Integration: Perfectly aligns with Filament v3’s custom field architecture, leveraging its Form and Infolist components. The package extends Filament’s field system without requiring invasive changes to the core application.
• Geo-Spatial Use Cases: Ideal for applications requiring location-based data (e.g., real estate, logistics, event management) where OpenStreetMap integration is a priority.
• GeoMan Synergy: Adds advanced vector editing capabilities (polygons, polylines, etc.) via GeoMan, broadening use cases beyond simple markers to spatial data modeling.

Integration Feasibility

• Low Friction: Composer-based installation with minimal boilerplate. Configuration is declarative (e.g., Map::make()), reducing integration complexity.
• State Management: Supports real-time coordinate updates via afterStateUpdated/afterStateHydrated, enabling seamless sync with database fields (e.g., latitude, longitude, geojson).
• Dynamic Data: Closures for default locations (e.g., fn ($record) => $record->latitude) allow runtime flexibility, critical for CRUD operations.

Technical Risk

• Dependency Stability:
  • Relies on Filament v3 (stable) and Leaflet.js (via GeoMan) for map rendering. Risk is mitigated by the package’s active maintenance (last release: 2026-05-04).
  • OpenStreetMap Tiles: Free tier may introduce rate limits for high-traffic apps; alternatives (e.g., Mapbox) could require custom tile URLs.
• GeoMan Complexity:
  • Advanced features (e.g., polygon editing) add JavaScript/CSS overhead. Test thoroughly for performance in forms with many fields.
  • Browser Compatibility: Ensure target browsers support Leaflet.js (v1.9+) and GeoMan.
• Data Serialization:
  • GeoJSON handling requires proper validation (e.g., json_encode/json_decode in afterStateUpdated). Edge cases (malformed GeoJSON) may need error handling.

Key Questions

1. Performance:
   • How will map rendering scale in forms with 10+ fields? Test with extraStyles to avoid layout shifts.
   • Does GeoMan’s vector editing introduce noticeable latency for complex geometries?
2. Data Model:
   • Should geojson be stored as a JSON column in the database, or normalized into separate tables for large geometries?
3. Customization:
   • Are there plans to support additional tile providers (e.g., Mapbox, Google Maps) via configuration?
4. Accessibility:
   • Does the map field meet WCAG standards (e.g., keyboard navigation, screen reader support)? Consider adding ARIA labels.
5. Offline Support:
   • Can the map work offline with cached tiles? If so, how to configure tile storage?

Integration Approach

Stack Fit

• Primary Use Case: Laravel + Filament v3 applications needing geo-spatial data input/output (e.g., admin panels, user profiles with location fields).
• Tech Stack Compatibility:
  • PHP: Requires PHP 8.1+ (Filament v3 baseline). No breaking changes expected.
  • JavaScript: Uses Leaflet.js (included via GeoMan) for map rendering. Ensure no conflicts with existing JS bundles (e.g., Alpine.js, Vue).
  • Database: Supports storing coordinates as latitude/longitude (float) or geojson (JSON/TEXT). Recommended schema:

    $table->decimal('latitude', 10, 8)->nullable();
    $table->decimal('longitude', 11, 8)->nullable();
    $table->json('geojson')->nullable(); // For GeoMan-generated data
    

• Alternatives Considered:
  • Filament Spatial: If needing PostgreSQL PostGIS integration, this package may be lighter but lacks GeoMan’s editing tools.
  • Custom Solution: Rolling your own map field would require ~3x the effort for similar functionality.

Migration Path

1. Pilot Phase:
   • Start with a single resource (e.g., LocationResource) to test basic marker functionality.
   • Validate afterStateUpdated logic for syncing latitude/longitude to the database.
2. GeoMan Rollout:
   • Gradually enable GeoMan features (e.g., polygons) in resources where complex geometries are needed.
   • Monitor JavaScript errors in browser console during editing sessions.
3. Performance Optimization:
   • Use draggable(false) for read-only maps (e.g., Infolist) to reduce resource usage.
   • Lazy-load tiles with minZoom/maxZoom constraints to limit bandwidth.

Compatibility

• Filament Versions: Explicitly targets Filament v3 (^1.8). Avoid mixing with Filament v2.
• Leaflet Plugins: GeoMan relies on Leaflet plugins (e.g., leaflet-geoman). Ensure no version conflicts with existing Leaflet usage.
• CSS Conflicts: Custom extraStyles may override Filament’s default styling. Use !important sparingly; prefer BEM classes.

Sequencing

1. Core Integration:
   • Install package and add Map field to a form.
   • Test basic marker placement and coordinate retrieval.
2. Advanced Features:
   • Enable geoMan(true) and validate vector editing UX.
   • Test rangeSelectField with distance-based logic (e.g., "Show venues within 5km").
3. Edge Cases:
   • Simulate slow network conditions to test tile loading.
   • Verify boundaries work as expected (e.g., preventing selection outside a region).
4. Deployment:
   • Ensure tile URLs (e.g., OpenStreetMap) are accessible in production.
   • Cache GeoJSON data if frequent reads are expected.

Operational Impact

Maintenance

• Package Updates:
  • Monitor dotswan/filament-map-picker for breaking changes (e.g., GeoMan API updates).
  • Test upgrades in a staging environment before production.
• Dependency Management:
  • Pin Leaflet.js/GeoMan versions in composer.json if using custom builds.
  • Watch for OpenStreetMap tile provider changes (e.g., deprecated endpoints).
• Customizations:
  • Override default styles/icons via extraStyles/markerIconUrl to avoid forks.
  • Document non-standard configurations (e.g., custom tile layers).

Support

• User Training:
  • GeoMan’s advanced features (e.g., polygon editing) may require documentation or in-app tooltips.
  • Example: Add a help icon next to the map with instructions for drawing shapes.
• Troubleshooting:
  • Common issues:
    • Blank Map: Check tilesUrl and CORS for tile requests.
    • Marker Not Updating: Verify afterStateUpdated logic and Set usage.
    • GeoMan Errors: Ensure Leaflet plugins are loaded (check browser console).
  • Debugging tools:
    • Leaflet’s built-in dev tools (right-click map → "Inspect").
    • Filament’s wire:log for state updates.

Scaling

• Performance:
  • Large Forms: Disable geoMan or reduce maxZoom if map rendering lags.
  • High Traffic: Consider a CDN for OpenStreetMap tiles or switch to a commercial provider (e.g., Mapbox).
  • Database: Index latitude/longitude columns for spatial queries (e.g., ->whereRaw('ST_DWithin(..., POINT(longitude, latitude), 5000)')).
• Concurrency:
  • liveLocation updates may increase database writes. Throttle with milliseconds or queue updates (e.g., Laravel Queues).
  • Use optimistic locking for concurrent edits to geometries.

Failure Modes

Ramp-Up

• Onboarding:
  • Developers:
    • Provide a MapFieldUsage.md with examples for common use cases (e.g., "How to store GeoJSON").
    • Highlight critical methods: afterStateUpdated, defaultLocation, geoMan.
  • End Users:
    • Add a tooltip or modal explaining how to use the map (e.g., "Click to place a marker").
• Documentation Gaps:
  • Missing: Performance tuning guide, GeoMan API reference, custom tile provider setup.
  • **Suggested Additions