Geo Bundle Laravel Package

Product Decisions This Supports

• Geospatial Features in Roadmap: Accelerates development of location-based features (e.g., "Find nearby X," "Delivery radius," or "Distance-based filtering") without relying on external APIs (cost, latency, or rate limits).
• Build vs. Buy: Avoids building custom geospatial logic from scratch (e.g., Haversine formula implementations, geocoding pipelines) or integrating third-party services (e.g., Google Maps API, Mapbox). Reduces technical debt by leveraging Doctrine’s query layer.
• Performance-Critical Use Cases:
  • Database-Driven Distance Queries: Enables efficient WHERE clauses (e.g., SELECT * FROM users WHERE GEO_DISTANCE(lat, lng, :targetLat, :targetLng) < 10) without client-side calculations.
  • Postal Code Lookups: Supports country-specific distance calculations (e.g., "Show users within 50km of Berlin’s postal code range") without API calls.
• Data Privacy/Offline Capabilities: Ideal for apps requiring geospatial functionality without exposing user locations to external services (e.g., healthcare, logistics, or internal tools).
• Monetization via Location: Enables features like "Premium radius expansion" (e.g., "Upgrade to see 50km instead of 10km") with minimal backend changes.

When to Consider This Package

• Avoid if:
  • Real-Time Geocoding Needed: Requires converting addresses to coordinates (e.g., "Find all users near '1600 Pennsylvania Ave'"). This bundle assumes coordinates/postal codes are pre-stored.
  • Complex Geoshapes: Need polygons, buffers, or advanced GIS operations (e.g., "Show all users within this irregular boundary"). Consider PostGIS or Elasticsearch’s geo_point instead.
  • High-Volume Dynamic Data: Postal code data must be manually imported/updated (e.g., for global apps). External services (e.g., OpenStreetMap) may scale better.
  • Non-Symfony Stack: Uses Symfony/Doctrine; alternatives like PostGIS (SQL) or Turf.js (JavaScript) may fit better.
  • Precision Requirements: Returns distances in kilometers only; for meters or other units, custom logic may be needed.
• Consider Alternatives When:
  • Hybrid Approach: Combine with a geocoding API (e.g., use GEO_DISTANCE for stored coordinates but call an API for address-to-coordinate conversion).
  • Global Scale: Need up-to-date postal code data across countries (may require manual maintenance or a paid dataset).
  • Frontend Interactivity: Require client-side maps/filters (pair with Leaflet.js or Mapbox GL).

How to Pitch It (Stakeholders)

For Executives: "This package lets us build location-based features—like ‘Find nearby stores’ or ‘Delivery radius’—without relying on expensive third-party APIs. It works entirely within our database, so it’s fast, reliable, and doesn’t add per-request costs. For example, we could offer a ‘Premium’ feature where users expand their search radius, all while keeping data private and performance high. It’s a low-risk way to add geospatial capabilities quickly."

For Engineers: *"CraueGeoBundle adds two Doctrine DQL functions to Symfony:

1. GEO_DISTANCE(lat1, lng1, lat2, lng2): Calculate distance between two coordinates in a single SQL query (no PHP loops or client-side math).
2. GEO_DISTANCE_BY_POSTAL_CODE(country, code1, code2): Distance between postal codes (requires one-time data import).

• Pros: Zero external dependencies, works offline, integrates seamlessly with Doctrine queries.
• Cons: Postal code data must be pre-loaded (we’d need to source/update it), and it’s km-only. For most use cases, this is a 10x faster alternative to rolling our own Haversine logic or calling APIs per query.
• Next Steps: I’d recommend a spike to test performance with our expected query patterns and confirm the postal code data coverage we need."*

For Data Teams: "This could reduce API costs and latency for location-based queries. For example, instead of fetching all users and calculating distances in PHP, we’d filter results at the database level. We’d need to ensure our user/postal code data includes latitude/longitude or postal codes, but the tradeoff is worth it for scalability."