DEV Community: Eduar Bastidas

Server-Side Geolocation Filtering in Laravel with the Haversine Formula

Eduar Bastidas — Sun, 06 Jul 2025 04:15:20 +0000

Distance-aware queries are a core feature for modern apps—whether you're matching riders and drivers, showing events around a user, or surfacing the nearest warehouses for same-day delivery. The fastest, most accurate way to deliver those results is to compute great-circle distance inside your SQL engine with the Haversine formula, then let Eloquent give you a fluent, testable API.

Why Haversine?

Mathematically sound. Haversine treats Earth as a sphere, producing realistic distances at planetary scale without the overhead of full ellipsoidal calculations.

Pushes work to the DB. The heavy trig runs where your data already lives, slicing result sets before PHP ever sees them.

Vendor-agnostic. Works in MySQL, MariaDB, Postgres, SQL Server—anything that supports basic trig functions.

The Math — Haversine Engine, No Mystery

The Haversine formula gives the great-circle distance between two points on a sphere:

Formula on my blog

Plugging those values in returns the shortest surface distance (the great-circle distance)—ideal for any geospatial filter you need on the server.

The Data Model

We'll generalise first and then pivot to a concrete example:

Table	Purpose	Key Columns
`trips` (or any parent entity)	The object you're filtering from	`id`, …
`coordinates`	Latitude/longitude pairs representing nearby entities (cars, stores, users, etc.)	`id`, `latitude`, `longitude`, `trip_id`

Trip ➜ hasMany ➜ Coordinate

Coordinate ➜ belongsTo ➜ Trip

You can just as easily embed latitude and longitude directly on the primary model. The scope below works in either scenario; choosing a relation simply keeps the example laser-focused on nearest cars for a given trip.

The Scope

use Illuminate\Database\Eloquent\Builder;

/**
 * Scope a query to include only records within a given radius.
 *
 * @param  \Illuminate\Database\Eloquent\Builder  $query
 * @param  float|int  $distance
 * @param  float  $lat
 * @param  float  $lng
 * @param  string  $units
 * @return \Illuminate\Database\Eloquent\Builder
 */
public function scopeDistance(Builder $query, float|int $distance, float $lat, float $lng, string $units = 'kilometers')
{
    if (!$distance || !$lat || !$lng) {
        return $query; // nothing to filter
    }

    $radius = $units === 'miles' ? 3959 : 6371; // Earth radius

    // Haversine formula (placeholders only)
    $haversine = "(
        ? * ACOS(
            COS(RADIANS(?)) *
            COS(RADIANS(coordinates.latitude)) *
            COS(RADIANS(coordinates.longitude) - RADIANS(?)) +
            SIN(RADIANS(?)) *
            SIN(RADIANS(coordinates.latitude))
        )
    )";

    $bindings = [$radius, $lat, $lng, $lat];

    return $query->whereHas('coordinates', fn ($q) =>
        $q->selectRaw("ROUND($haversine, 2) AS distance", $bindings)
          ->having('distance', '<=', $distance)
          ->orderBy('distance', 'asc')
    );
}

Decisive details:

Units are explicit. No hidden constants—callers pass 'miles' or 'kilometers'.
Select + having. We compute distance and filter in one trip to the database.
Relation-aware. whereHas ensures we only pull Trip rows that have at least one qualifying Coordinate.

Practical Example: Finding Cars Near a Trip

$nearbyCars = Trip::byDistance(
        distance: 10, // 10 km radius
        lat: $trip->pickup_lat,
        lng: $trip->pickup_lng,
        units: 'kilometers'
    )
    ->with('coordinates') // eager-load matches
    ->get();

Swap Trip and Coordinate for any other domain pair—warehouses and parcels, events and attendees, sellers and buyers.

If You Store Lat/Lng on the Same Table

Just remove the whereHas wrapper and call selectRaw / having directly on $query. Everything else remains identical.

$query->selectRaw($haversine)
      ->having('distance', '<=', $distance)
      ->orderBy('distance');

Performance Power-Ups

Technique	Why It Matters
Composite index on `(latitude, longitude)`	Accelerates simple bounding-box prefilters.
Bounding box guard-clause	`whereBetween` lat/lng to skip obvious misses before running trig.
Spatial columns	`POINT` + `SPATIAL INDEX` (MySQL) or PostGIS geography types let you switch to `ST_DistanceSphere` later with a one-liner.
Query caching	City-scale apps see repetitive origins—cache JSON responses for 30–60 s.

Testing the Scope

test('returns coordinates within radius', function () {
    $origin = ['lat' => 10.5000, 'lng' => -66.9167];

    Coordinate::factory()->create(['latitude' => 10.51, 'longitude' => -66.91]); // ~1 km
    Coordinate::factory()->create(['latitude' => 11.00, 'longitude' => -67.00]); // ~70 km

    $results = Trip::byDistance(5, $origin['lat'], $origin['lng'])->get();

    expect($results)->toHaveCount(1);
});

Fast, deterministic, no external APIs.

Final Thoughts

The Haversine formula is universally applicable—anywhere you need "X within Y km". By embedding it in a concise Eloquent scope, you gain:

Zero vendor lock-in. Works the same across MySQL, MariaDB, Postgres, or SQL Server.
Uncompromising performance. The database filters; PHP just maps results to resources.
Readable, testable code. Your controllers stay slim, your models self-document intent.

Copy the scope, adjust the relationship (or not), and ship precise geospatial queries!.

How to Stream Large File Uploads to AWS S3 in Laravel

Eduar Bastidas — Sun, 06 Jul 2025 04:11:57 +0000

Handling multi‑gigabyte uploads in a stateless app is painful: TCP throughput caps slow single‑request uploads, server disks fill, and Lambda containers vanish between requests. Modern teams therefore push the heavy bits straight from the browser to Amazon S3. S3M—a lean wrapper around S3's multipart and presigned‑URL APIs—removes the boilerplate. S3M works with any JavaScript front‑end, but in this post I'll give you some examples using Vue so you can see the flow end‑to‑end without locking you into a specific framework.

Why multipart + presigned URLs?

Amazon limits a single PUT to 5 GB. Multipart uploads slice the object, let slices fly in parallel, and re‑assemble the completed object inside S3. Presigned URLs add a time‑boxed signature, allowing the browser to upload directly to S3 while your API remains stateless and credential‑free. In practice the flow has four distinct calls: initiate, sign, upload parts, complete.

Prerequisites

Laravel 10 or newer with an s3 disk configured in config/filesystems.php.
AWS IAM user or role able to call s3:PutObject, s3:AbortMultipartUpload, s3:CompleteMultipartUpload, and s3:ListMultipartUploadParts.
Front‑end: any framework (React, Vue, Alpine, plain JS). The snippets below use Vue for clarity.
Composer & Node.

1 – Install the helper

composer require mreduar/s3m

Add the Blade directive before your compiled JS so the global s3m() helper is injected:

{{-- resources/views/layouts/app.blade.php --}}
<!doctype html>
<html>
  <head>
      @s3m   {{-- pushes the small JS bridge into the page --}}
      @vite('resources/js/app.js')
  </head>
  <body class="antialiased">
      @yield('content')
  </body>
</html>

The directive publishes a 3‑kB script that negotiates presigned URLs when you call s3m(file, options) on the client.

2 – Publish and tweak config

php artisan vendor:publish --provider="MrEduar\S3M\S3MServiceProvider"

config/s3m.php exposes sensible defaults—10 MB chunks, four parallel PUTs, three automatic retries per part. When your audience has slow upstream links, dial the part_size down (the minimum is 5 MB except for the last part) to shorten retry times.

3 – Gate uploads with a policy

S3M calls Laravel's authorization layer before handing out any presigned URLs. Create a policy if you don't already have one:

php artisan make:policy UserPolicy --model=User

public function uploadFiles(User $user): bool
{
    return $user->plan()->allows('large_upload');
}

This guarantees that an attacker can't obtain a signed URL unless the current user meets your business rules.

4 – Expose a controller endpoint

While S3M can wire routes for you, most teams prefer an explicit controller to attach domain metadata:

Route::post('/api/profile-photo', ProfilePhotoController::class);

Inside you can move the temporary object out of tmp/ after the browser confirms completion:

Storage::copy($request->key, Str::after($request->key, 'tmp/'));

You now hold the stable S3 key that maps to the uploaded file.

5 – Front‑end example (Vue)

The helper works with any framework; swap the snippet for React, Alpine, or vanilla JS as needed. Below is a Vue Composition‑API component that streams the selected file:

<script setup>
import { ref } from 'vue'
import axios from 'axios'

const progress = ref(0)

function upload(e) {
  const file = e.target.files[0]

  s3m(file, {
    progress: p => progress.value = p
  }).then(({ uuid, key, bucket }) => axios.post('/api/profile-photo', {
      uuid, key, bucket,
      name: file.name,
      content_type: file.type,
  }))
}
</script>

<template>
  <input type="file" @change="upload" />
  <progress :value="progress" max="100" class="w-full" />
</template>

Under the hood s3m() performs initiate → get signed parts → parallel PUTs → complete in fewer than 150 lines of unobtrusive JavaScript.

6 – Make the upload permanent

Every object lands in tmp/ so abandoned uploads can be purged by an S3 lifecycle rule after 24 h. A service class might promote the file once your app accepts it:

public function promote(string $key): string
{
    $finalKey = Str::after($key, 'tmp/')
    Storage::disk('s3')->copy($key, $finalKey);
    return $finalKey; // stable key without the tmp/ prefix
}

Pro tips for production

Chunk size trade‑offs – parts must be at least 5 MB (except the last). Aim for 8–15 MB to balance retry latency and TLS overhead.
Transfer Acceleration – If users upload from distant regions, enabling S3 Transfer Acceleration routes traffic through the nearest CloudFront edge and can shave seconds off large uploads.
CORS headers – Expose ETag and allow PUT, POST, GET, HEAD so the browser can send part signatures back during completion.
Observability – Log the UploadId, part numbers, and user ID; correlating failures in CloudWatch or Kibana becomes trivial.

Closing thoughts

With S3M you glue a single Blade directive on the front end and one controller on the back end, yet you gain a resumable, parallel‑chunked upload pipeline that never blocks PHP workers and never exposes AWS credentials to the client. Adapt the Vue snippet to any framework—or even plain JavaScript—and you'll stream large files to S3 with confidence.