Filament Pinpoint Laravel Package

Technical Evaluation

Architecture Fit

• Filament Integration: Seamlessly integrates with Filament 4/5, leveraging its form/infolist architecture. The package extends Filament’s native field system (Pinpoint for forms, PinpointEntry for read-only views), ensuring consistency with existing UI patterns.
• Modular Design: Supports both Google Maps (API-dependent) and Leaflet/OpenStreetMap (free, no API key), allowing flexibility based on budget/requirements. The dual-provider approach aligns with modern geo-spatial needs (e.g., cost-sensitive vs. high-precision use cases).
• Component-Based: Encapsulates map logic into reusable components, reducing boilerplate for location-based features (e.g., search, reverse geocoding, radius tools). Ideal for CRUD-heavy applications (e.g., real estate, logistics, field service).
• Filament Ecosystem Synergy: Works natively with Filament’s Repeater, Infolist, and form validation, enabling complex scenarios like multi-location entries (e.g., branch networks) without custom JS.

Integration Feasibility

• Low Friction: Requires minimal setup (Composer install + env config). No custom Blade views or JS bundles needed—fully PHP-driven.
• Database Agnostic: Maps to existing lat/lng fields (or custom field names), avoiding schema changes. Reverse geocoding auto-populates address fields (e.g., street, city), reducing manual data entry.
• API Key Management: Google Maps requires an API key (with enabled APIs), but Leaflet offers a zero-cost alternative. The package abstracts key management via .env, simplifying compliance.
• Localization: Built-in support for EN/AR/NL/ID/ES, reducing i18n overhead for multilingual apps.

Technical Risk

• Google Maps Costs: Usage-based pricing for Google Maps could escalate costs at scale (e.g., high-traffic admin panels). Mitigation: Use Leaflet for non-critical views or limit Google Maps to essential workflows.
• Dependency on External APIs:
  • Google: Rate limits and potential deprecation of APIs (e.g., Places Autocomplete).
  • Leaflet/Nominatim: OpenStreetMap’s Nominatim service has usage policies (e.g., no automated queries). Risk: IP blocking or throttling under heavy load.
  • Mitigation: Cache geocoding responses (e.g., Redis) or use a local geocoding service (e.g., PhpGeocoder).
• Performance:
  • Large maps or high-zoom levels may impact page load times (Google Maps JS library is ~100KB+).
  • Leaflet is lighter but may lack polish for professional use cases.
  • Mitigation: Lazy-load maps or use height() to constrain resource usage.
• Customization Limits:
  • Advanced map interactions (e.g., custom layers, 3D views) require manual JS integration.
  • Radius tool is basic (no distance units customization beyond meters).
• Filament Version Lock: Explicitly supports Filament 4/5. Upgrades to Filament 6+ may require vendor updates.

Key Questions

1. Provider Strategy:
   • Will the app use Google Maps (for premium features like high-accuracy geocoding) or Leaflet (cost savings)?
   • If hybrid, how will provider selection be managed (e.g., per-field vs. global config)?
2. Cost Governance:
   • For Google Maps, what’s the budget for API usage? Are there tools to monitor/alert on cost spikes?
3. Offline/High-Availability Needs:
   • Does the app require offline map support or failover to static maps if APIs fail?
4. Data Privacy:
   • Are there GDPR/regulatory constraints on storing user location data (e.g., current device location)?
5. Scalability:
   • How many concurrent users will interact with maps? Will Leaflet’s free tier suffice, or are there risks of IP blocking?
6. Customization Depth:
   • Are there plans to extend map features (e.g., heatmaps, routes) beyond the package’s scope?
7. Testing:
   • How will geocoding accuracy be validated (e.g., edge cases like rural addresses or non-Latin scripts)?
8. Fallbacks:
   • What’s the plan if Google Maps/Leaflet APIs are unavailable (e.g., static map fallback)?

Integration Approach

Stack Fit

• Laravel/PHP: Native integration with Laravel’s service providers, config publishing, and Filament’s form system. No framework-specific hacks required.
• Filament 4/5: Designed as a first-class citizen for Filament’s form/infolist architecture. Supports all Filament features (e.g., repeaters, validation, livewire reactivity).
• Frontend:
  • Google Maps: Uses the official Google Maps JavaScript API (loaded dynamically).
  • Leaflet: Uses Leaflet.js (~40KB) + OpenStreetMap tiles (no API key).
  • Both providers support dark mode and responsive design.
• Database: Works with any Laravel-supported DB (MySQL, PostgreSQL, etc.). No migrations required—just ensure lat/lng fields exist.

Migration Path

1. Assessment Phase:
   • Audit existing location fields (e.g., lat, lng, address). Identify gaps (e.g., missing city, postal_code).
   • Decide on provider strategy (Google/Leaflet/hybrid) based on cost and feature needs.
2. Setup:
   • Install via Composer:

     composer require fahiem/filament-pinpoint
     

   • Configure .env:

     PINPOINT_PROVIDER=leaflet  # or 'google'
     GOOGLE_MAPS_API_KEY=your_key  # if using Google
     

   • Publish config (optional):

     php artisan vendor:publish --tag="filament-pinpoint-config"
     

3. Incremental Rollout:
   • Phase 1: Replace basic text inputs for lat/lng with Pinpoint in forms.
   • Phase 2: Add reverse geocoding to auto-fill address fields (e.g., street, city).
   • Phase 3: Implement PinpointEntry for read-only views (e.g., infolists).
   • Phase 4: Add advanced features (e.g., radius, current location, repeaters).
4. Testing:
   • Validate geocoding accuracy for critical locations (e.g., HQ, customer sites).
   • Test edge cases: invalid coordinates, API timeouts, offline mode.
   • Performance test with concurrent users (especially for Leaflet).

Compatibility

• Filament Features:
  • ✅ Forms (create/edit)
  • ✅ Infolists (read-only)
  • ✅ Repeaters (multi-location entries)
  • ✅ Validation (e.g., required fields)
  • ✅ Livewire reactivity (real-time updates)
  • ✅ Dark mode
  • ✅ Localization
• Laravel Features:
  • ✅ Eloquent models (maps to DB fields)
  • ✅ Query scopes (e.g., filter by radius)
  • ✅ API responses (serializes lat/lng as needed)
• Third-Party:
  • Google Maps: Requires enabled APIs (Maps JS, Places, Geocoding).
  • Leaflet: No dependencies beyond OpenStreetMap tiles (default) or custom tile servers.

Sequencing

1. Core Integration:
   • Replace existing lat/lng text inputs with Pinpoint in forms.
   • Example:

     Pinpoint::make('location')
         ->latField('latitude')
         ->lngField('longitude')
         ->addressField('address')
         ->searchable()
         ->draggable();
     

2. Enhancements:
   • Add reverse geocoding to populate city, postal_code, etc.
   • Implement PinpointEntry for infolists.
3. Advanced Features:
   • Enable radius tools for location-based queries (e.g., "show all branches within 10km").
   • Use current location for mobile-friendly workflows.
4. Optimization:
   • Lazy-load maps or debounce geocoding requests.
   • Cache frequent geocoding results (e.g., Redis).

Operational Impact

Maintenance

• Vendor Updates:
  • Monitor the package for Filament 6+ compatibility.
  • Update dependencies (e.g., Leaflet, Google Maps JS) as needed.
• Configuration Drift:
  • Centralize map settings (e.g., default zoom, height) in config to avoid hardcoding.
  • Use environment variables for provider-specific settings (e.g., GOOGLE_MAPS_API_KEY).
• Geocoding Accuracy:
  • Periodically validate address auto-fill (e.g., compare with manual entries).
  • Handle edge cases (e.g., non-standard addresses, non-Latin scripts).

Support

• User Training:
  • Document how to use the map picker (e.g., search