Fft Laravel Package

Product Decisions This Supports

• Build vs. buy/borrow: Removes any justification for hand-rolling haversine/great-circle math in application code. A tested, maintained dependency is cheaper to own than bespoke trigonometry scattered across services.
• Feature enablement: Unlocks or de-risks any feature driven by coordinate-pair distance computation — store/asset locators, "nearest to me" sorting, delivery-radius and service-area eligibility, geo-fenced pricing, marketplace matching, event/listing discovery, and proximity notifications.
• Roadmap sequencing: A ~20% throughput gain inside batch loops (the release specifically optimizes repeated iteration over similarly sized datasets) changes the cost curve on previously shelved "compute distances for everything, then rank" features. Work that was deferred as too expensive per request can be re-evaluated for the next cycle.
• Infra and cost posture: Higher per-process throughput on location-heavy endpoints and jobs means we can absorb growth in coordinates, candidates, or nightly recompute volume without a proportional increase in workers or DB read replicas. Useful ammunition for the "optimize before we scale horizontally" argument.
• SLA/UX decisions: Cheaper distance loops translate into more candidate points we can afford to score synchronously, which directly affects result quality (bigger search radius, more complete ranking) versus latency budgets.
• Prioritization guardrail: Because this is a micro-optimization patch to a narrow computation, it should not anchor a roadmap narrative. It's an enabling efficiency, not a headline feature. Treat it as an input to sizing, not to strategy.

When to Consider This Package

Adopt when:

• You compute many coordinate-pair distances per request or job — hundreds to millions — rather than a single one-off lookup. The 1.0.1 win is scoped to iterating multiple datasets of the same length, so the payoff scales with loop-heavy, batch-shaped workloads.
• Your distance workloads repeat with consistent shapes (same-size candidate sets, per-page grids, scheduled recomputes). That's precisely the pattern the sin/cos caching targets; irregular, one-shot calls will see little of the 20%.
• You want a small, deterministic, testable dependency instead of inline spherical math, and you're comfortable accepting a Composer dependency in the request path.
• Spherical (haversine-style) accuracy is adequate for the product — radius filters, ranking, "within N km" checks. This is true for the large majority of locator and matching features.
• You're already on Laravel/PHP and want the calculation co-located with domain logic rather than pushed into a stored procedure or external service.

Look elsewhere or complement when:

• You need database-native spatial filtering at scale — PostGIS, MySQL spatial indexes, or a geospatial search engine should own the coarse "which candidates are in the box" query. This package is the scoring layer, not a replacement for spatial indexes.
• You need drive time, routing, or isochrones — that requires a routing provider, not geometry math.
• You need higher-order geodesic accuracy (Vincenty, ellipsoidal models) for surveying, compliance, or very long intercontinental distances.
• You need map rendering, tiles, GeoJSON authoring, or geocoding — different problem space.
• Your volume is small. A single distance per page render will not notice a 20% micro-optimization; the dependency is still defensible for correctness and maintainability, but don't justify it on performance.
• You're sensitive to a young API surface. A 1.0.x line with a performance-focused patch suggests active maintenance but also an evolving interface — pin versions and wrap usage behind a thin internal adapter so a future major bump is a one-file change.

Validation before adoption: benchmark against our real workload shapes, not the maintainer's equal-length dataset benchmark. If our candidate sets vary in size per call, confirm the caching still applies before quoting the 20% internally.

How to Pitch It (Stakeholders)

For executives (one paragraph): A small, low-risk PHP dependency for location-based calculations shipped a patch release that makes repeated distance computations roughly 20% faster. That directly improves throughput on any feature that ranks or filters by proximity — locators, radius-based delivery and pricing, marketplace matching — without new infrastructure or a re-architecture. There are no breaking changes: it's a patch version, so the upgrade is a version bump and a regression run. The strategic read is modest but real — it lowers the marginal cost of proximity features we've previously deprioritized on cost grounds, and gives us headroom to serve more candidates per request at the same latency. Recommendation: approve as a routine dependency for the relevant services, adopt behind an internal adapter, and fund one short benchmark against our production-shaped workloads before we cite the 20% in any planning.

For engineering: Deterministic math utility, no API surface changes in 1.0.1 — the change caches sin/cos values that are invariant across calls, which is why the gain concentrates in loops over multiple datasets. Pin the version, wrap it in a thin internal service so the dependency isn't sprayed across the codebase, and add a benchmark fixture that mirrors our real call shapes (variable candidate-set sizes included) so the next performance claim is ours, not the changelog's. Pair it with database-side spatial indexing for the coarse candidate filter; this is the scoring layer, not the index.

For product: Treat this as unblocking, not as a feature. When scoping the next proximity-driven epic, assume distance scoring is now ~20% cheaper in batch paths and re-run the sizing — some items previously cut for performance reasons may now fit inside the latency budget.