README

Geospatial utilities for distance, bounding box, and point-in-polygon calculations.

Requirements

PHP 8.2+

Installation

composer require philiprehberger/php-geo

Usage

Distance Calculation (Haversine)

use PhilipRehberger\Geo\Coordinate;
use PhilipRehberger\Geo\Geo;

$nyc = new Coordinate(40.7128, -74.0060);
$la = new Coordinate(33.9425, -118.4081);

$km = Geo::distance($nyc, $la);          // ~3944 km
$miles = Geo::distance($nyc, $la, 'mi'); // ~2451 mi

Vincenty Distance

$km = Geo::distanceVincenty($nyc, $la); // More accurate for long distances

Bounding Box

$center = new Coordinate(40.7128, -74.0060);
$box = Geo::boundingBox($center, 10.0); // 10 km radius

$box->contains($center); // true
$box->toArray();          // ['min_lat' => ..., 'max_lat' => ..., 'min_lng' => ..., 'max_lng' => ...]

Point in Polygon

$polygon = [
    new Coordinate(40.800, -73.970),
    new Coordinate(40.800, -73.950),
    new Coordinate(40.760, -73.950),
    new Coordinate(40.760, -73.970),
];

$point = new Coordinate(40.780, -73.960);
Geo::contains($polygon, $point); // true

Bearing

$bearing = Geo::bearing($nyc, $la); // Initial bearing in degrees (0-360)

Midpoint

$mid = Geo::midpoint($nyc, $la); // Geographic midpoint

Destination

// Travel 100 km north from the equator
$start = new Coordinate(0.0, 0.0);
$dest = Geo::destination($start, 0.0, 100.0); // bearing=0 (north), 100 km

Compass Direction

$bearing = Geo::bearing($nyc, $la);
$direction = Geo::compassDirection($bearing); // e.g. 'SW'

Geo::compassDirection(0.0);   // 'N'
Geo::compassDirection(90.0);  // 'E'
Geo::compassDirection(225.0); // 'SW'

Elevation

$coord = new Coordinate(40.7128, -74.0060);
$elevated = $coord->withElevation(100.5); // New Coordinate with elevation
$elevated->getElevation(); // 100.5
$coord->getElevation();    // null (original unchanged)

Polygon Area

$polygon = [
    new Coordinate(0.0, 0.0),
    new Coordinate(0.0, 1.0),
    new Coordinate(1.0, 1.0),
    new Coordinate(1.0, 0.0),
];

$area = Geo::area($polygon); // Area in square meters

Geohash Encoding/Decoding

$coord = new Coordinate(57.64911, 10.40744);
$hash = Geo::encodeGeohash($coord);          // 'u4pruydqqvj8'
$decoded = Geo::decodeGeohash($hash);        // Coordinate near original
$bounds = Geo::geohashBounds($hash);         // BoundingBox of geohash cell

Polyline Encoding/Decoding

$coordinates = [
    new Coordinate(38.5, -120.2),
    new Coordinate(40.7, -120.95),
    new Coordinate(43.252, -126.453),
];

$encoded = Geo::encodePolyline($coordinates);  // '_p~iF~ps|U_ulLnnqC_mqNvxq`@'
$decoded = Geo::decodePolyline($encoded);      // Array of Coordinate objects

Route Distance

$route = [
    new Coordinate(40.7128, -74.0060),
    new Coordinate(41.8781, -87.6298),
    new Coordinate(33.9425, -118.4081),
];

$total = Geo::routeDistance($route); // Total distance in km

Units

Supported units: km (kilometers), mi (miles), m (meters), nmi (nautical miles).

Geo::distance($a, $b, 'mi');   // miles
Geo::distance($a, $b, 'm');    // meters
Geo::distance($a, $b, 'nmi');  // nautical miles

API

Method	Description
`Geo::distance($a, $b, $unit)`	Haversine distance between two coordinates
`Geo::distanceVincenty($a, $b, $unit)`	Vincenty distance between two coordinates
`Geo::boundingBox($center, $radius, $unit)`	Bounding box around a center point
`Geo::contains($polygon, $point)`	Point-in-polygon test (ray casting)
`Geo::bearing($from, $to)`	Initial bearing in degrees
`Geo::midpoint($a, $b)`	Geographic midpoint
`Geo::destination($start, $bearing, $distance, $unit)`	Destination from start given bearing and distance
`Geo::compassDirection($bearing)`	Convert bearing to cardinal/intercardinal direction
`Geo::area($polygon)`	Polygon area in square meters (Shoelace formula)
`Geo::encodeGeohash($coord, $precision)`	Encode coordinate to geohash string
`Geo::decodeGeohash($hash)`	Decode geohash to coordinate (center of cell)
`Geo::geohashBounds($hash)`	Get bounding box of a geohash cell
`Geo::encodePolyline($coordinates)`	Encode coordinates to Google polyline string
`Geo::decodePolyline($encoded)`	Decode Google polyline string to coordinates
`Geo::routeDistance($coordinates, $unit)`	Total distance along a multi-point route
`Coordinate::withElevation($meters)`	Return new Coordinate with elevation
`Coordinate::getElevation()`	Get elevation in meters or null

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT

philiprehberger / php-geo

Maintainers

Package info

Fund package maintenance!

Statistics

Security