Product Decisions This Supports
- Geospatial Features in Roadmap: Accelerates development of location-based features (e.g., "nearby X," distance filters, or delivery-time estimates) without relying on external APIs (cost, latency, or uptime risks).
- Build vs. Buy: Avoids building custom geospatial logic in Doctrine queries, reducing technical debt and maintenance overhead. Justifies "buy" for teams lacking geospatial DB expertise.
- Performance-Critical Use Cases: Enables real-time distance calculations in database queries (e.g., "show users within 50km of this coordinate"), improving response times vs. client-side calculations.
- Postal Code-Based Features: Supports country-specific distance calculations (e.g., "find all stores in Germany within 10km of postal code 10115"), useful for logistics, real estate, or local services.
- Offline Capability: Ideal for apps needing geospatial functionality without internet access (e.g., field service tools, offline maps).
When to Consider This Package
- Avoid if:
- Your app requires high-precision geospatial queries (e.g., complex polygons, geofencing) → Consider PostGIS or Elasticsearch.
- You need real-time geocoding (address → coordinates) → Use Google Maps API, OpenStreetMap, or a dedicated service.
- Your team lacks Doctrine/Symfony familiarity → May require additional setup for database schema migrations.
- You’re using non-Symfony PHP frameworks → Not applicable (Symfony-specific).
- Your distance calculations are simple (e.g., client-side Haversine formula) → Overkill for basic needs.
- Look elsewhere if:
- You need scalable geospatial indexing (e.g., billions of points) → PostGIS or specialized tools like MongoDB’s geospatial queries.
- Your data is global with frequent updates → External APIs (e.g., Mapbox) may stay current with postal code boundaries.
- You’re constrained by database vendor (e.g., SQL Server) → Limited compatibility with Doctrine functions.
How to Pitch It (Stakeholders)
For Executives:
"This package lets us add location-based features—like ‘find nearby stores’ or ‘calculate delivery distances’—without relying on third-party APIs. It’s self-hosted, so no cost per query or risk of downtime. For example, we could build a ‘radius search’ for our [X] feature in weeks, not months, while keeping all data private. The tradeoff? We’d need to pre-load postal code data once, but the long-term savings on API costs and dev time justify it."
For Engineering:
*"CraueGeoBundle adds two Doctrine functions to calculate distances:
GEO_DISTANCE: For latitude/longitude pairs (e.g., ‘distance between user’s GPS and store’).GEO_DISTANCE_BY_POSTAL_CODE: For country+postal code (e.g., ‘distance between ZIP 10001 and ZIP 90210’).
- Pros: Zero external dependencies, runs in DB queries (fast), MIT-licensed.
- Cons: Requires a one-time setup to import postal code data (schema + fixtures). Not a drop-in for complex geospatial needs.
- Use Case: Perfect for [specific feature, e.g., ‘driver-to-job distance matching’] where we need to filter or sort by distance in SQL."*
For Data Teams:
*"This bundle lets us query distances directly in SQL, which is more efficient than fetching all records and calculating distances in PHP. For example, instead of:
// Slow (client-side)
$nearbyStores = $repo->findAll();
$filtered = array_filter($nearbyStores, fn($store) => distance($userLatLng, $storeLatLng) < 50);
We’d do:
-- Fast (DB-side)
SELECT * FROM stores WHERE GEO_DISTANCE(:userLat, :userLng, lat, lng) < 50
This reduces server load and improves response times for location-heavy queries."*