serafim / geokit
Geo-Toolkit for PHP
Requires
- php: ^8.0
Requires (Dev)
- phpunit/phpunit: ^9.5
- vimeo/psalm: ^4.22
Replaces
- geokit/geokit: ^1.0
README
This is fork of 1.x branch of https://github.com/nickdnk/geokit compatible with PHP 8.0+.
Geokit is a PHP toolkit to solve geo-related tasks like:
-
Distance calculations.
-
Heading, midpoint and endpoint calculations.
-
Rectangular bounds calculations.
Installation
Install the latest version with Composer.
composer require serafim/geokit
Check the Packagist page for all available versions.
Reference
Math
A Math instance can be used to perform geographic calculations on LatLng and
Bounds instances. Since such calculations depend on an
Earth Ellipsoid, you can pass an
instance of Geokit\Ellipsoid
to its constructor. If no Ellipsoid instance is
provided, it uses the default
WGS 86 Ellipsoid.
$math = new Geokit\Math(); $mathAiry = new Geokit\Math(Geokit\Ellipsoid::airy1830());
Distance calculations
A math instance provides two methods to calculate the distance between 2 points on the Earth's surface:
distanceHaversine($from, $to)
: Calculates the approximate sea level great circle (Earth) distance between two points using the Haversine formula.distanceVincenty($from, $to)
: Calculates the geodetic distance between two points using the Vincenty inverse formula for ellipsoids.
$distance1 = $math->distanceHaversine($from, $to); $distance2 = $math->distanceVincenty($from, $to);
Both methods return a Distance instance.
Transformations
With the expand
and shrink
methods, you can expand/shrink a given Bounds or
LatLng instance by a distance.
$expandedBounds1 = $math->expand(['lat' => 49.50042565 'lng' => 8.50207515], '10km'); $expandedBounds2 = $math->expand(Geokit\Bounds::normalize('-45 179 45 -179'), '10km'); $shrinkedBounds = $math->shrink($expandedBounds2, '10km');
Other calculations
Other useful methods are:
heading($from, $to)
: Calculates the (initial) heading from the first point to the second point in degrees.midpoint($from, $to)
: Calculates an intermediate point on the geodesic between the two given points.endpoint($start, $heading, $distance)
: Calculates the destination point along a geodesic, given an initial heading and distance, from the given start point.
Distance
A Distance instance allows for a convenient representation of a distance unit of measure.
$distance = new Geokit\Distance(1000); // or $distance = new Geokit\Distance(1, Geokit\Distance::UNIT_KILOMETERS); $meters = $distance->meters(); $kilometers = $distance->kilometers(); $miles = $distance->miles(); $feet = $distance->feet(); $nauticalMiles = $distance->nautical();
Alternatively, you can create a Distance instance through its static normalize method. This method takes anything which looks like distance and generates a Distance object from it.
$distance = Geokit\Distance::normalize(1000); // Defaults to meters $distance = Geokit\Distance::normalize('1000m'); $distance = Geokit\Distance::normalize('1km'); $distance = Geokit\Distance::normalize('100 miles'); $distance = Geokit\Distance::normalize('1 foot'); $distance = Geokit\Distance::normalize('234nm');
LatLng
A LatLng instance represents a geographical point in latitude/longitude coordinates.
- Latitude ranges between -90 and 90 degrees, inclusive. Latitudes above 90 or below -90 are capped, not wrapped. For example, 100 will be capped to 90 degrees.
- Longitude ranges between -180 and 180 degrees, inclusive. Longitudes above 180 or below -180 are wrapped. For example, 480, 840 and 1200 will all be wrapped to 120 degrees.
$latLng = new Geokit\LatLng(1, 2); $latitude = $latLng->getLatitude(); // or $latitude = $latLng['latitude']; $longitude = $latLng->getLongitude(); // or $longitude = $latLng['longitude'];
Alternatively, you can create a LatLng instance through its static normalize method. This method takes anything which looks like a coordinate and generates a LatLng object from it.
$latLng = Geokit\LatLng::normalize('1 2'); $latLng = Geokit\LatLng::normalize('1, 2'); $latLng = Geokit\LatLng::normalize(array('latitude' => 1, 'longitude' => 2)); $latLng = Geokit\LatLng::normalize(array('lat' => 1, 'lng' => 2)); $latLng = Geokit\LatLng::normalize(array('lat' => 1, 'lon' => 2)); $latLng = Geokit\LatLng::normalize(array(1, 2));
Bounds
A Bounds instance represents a rectangle in geographical coordinates, including one that crosses the 180 degrees longitudinal meridian.
It is constructed from its left-bottom (south-west) and right-top (north-east) corner points.
$southWest = new Geokit\LatLng(1, 2); $northEast = new Geokit\LatLng(1, 2); $bounds = new Geokit\Bounds($southWest, $northEast); $southWestLatLng = $bounds->getSouthWest(); // or $southWestLatLng = $bounds['south_west']; $northEastLatLng = $bounds->getNorthEast(); // or $northEastLatLng = $bounds['north_east']; $centerLatLng = $bounds->getCenter(); // or $centerLatLng = $bounds['center']; $spanLatLng = $bounds->getSpan(); // or $spanLatLng = $bounds['span']; $boolean = $bounds->contains($latLng); $newBounds = $bounds->extend($latLng); $newBounds = $bounds->union($otherBounds);
Alternatively, you can create a Bounds instance through its static normalize method. This method takes anything which looks like bounds and generates a Bounds object from it.
$bounds = Geokit\Bounds::normalize('1 2 3 4'); $bounds = Geokit\Bounds::normalize('1 2, 3 4'); $bounds = Geokit\Bounds::normalize('1, 2, 3, 4'); $bounds = Geokit\Bounds::normalize(array('south_west' => $southWestLatLng, 'north_east' => $northEastLatLng)); $bounds = Geokit\Bounds::normalize(array('south_west' => array(1, 2), 'north_east' => array(3, 4))); $bounds = Geokit\Bounds::normalize(array('southwest' => $southWestLatLng, 'northeast' => $northEastLatLng)); $bounds = Geokit\Bounds::normalize(array('southWest' => $southWestLatLng, 'northEast' => $northEastLatLng)); $bounds = Geokit\Bounds::normalize(array($southWestLatLng, $northEastLatLng));
Polygon
A Polygon instance represents a two-dimensional shape of connected line segments and may either be closed (the first and last point are the same) or open.
$polygon = new Geokit\Polygon([ new Geokit\LatLng(0, 0), new Geokit\LatLng(0, 1), new Geokit\LatLng(1, 1) ]); $latLng1 = $polygon[0]; $latLng2 = $polygon[1]; $latLng3 = $polygon[2]; $closedPolygon = $polygon->close(); $latLng4 = $closedPolygon[3]; // LatLng(0, 0) /** @var Geokit\LatLng $latLng */ foreach ($polygon as $latLng) { } $polygon->contains(LatLng(0.5, 0.5)); // true /** @var Geokit\Bounds $bounds */ $bounds = $polygon->toBounds();
License
Copyright (c) 2011-2016 Jan Sorgalla. Released under the MIT License.
Credits
Geokit has been inspired and/or contains ported code from the following libraries: