mjaschen/phpgeo

Simple Geo Library

Thursday, July 19, 2018
by marcusj
Repository
68 Watchers
979 Stars
252,661 Installations

PHP
6 Dependents
0 Suggesters
143 Forks
9 Open issues
34 Versions
16 % Grown

The README.md

phpgeo - A Simple Geo Library for PHP

phpgeo provides abstractions to geographical coordinates (including support for different ellipsoids) and allows you to calculate geographical distances between coordinates with high precision., _(*1)

, _(*2)

Requirements

Minimum required PHP version is 8.2. phpgeo is tested up to PHP 8.4., _(*3)

New features will only go into the main branch and won't be backported., _(*4)

It's possible to install older versions of phpgeo for older PHP versions. Please refer to the following table for the compatibility matrix:, _(*5)

PHP Version	phpgeo Version	Support Status	Composer Install
8.4	6.x	✅ active	`composer require mjaschen/phpgeo`
8.3	6.x	✅ active	`composer require mjaschen/phpgeo`
8.2	6.x	✅ active	`composer require mjaschen/phpgeo`
8.1	5.x	⚠️ security only	`composer require mjaschen/phpgeo:^5.0`
8.0	4.x	⚠️ security only	`composer require mjaschen/phpgeo:^4.0`
7.4	4.x	⚠️ security only	`composer require mjaschen/phpgeo:^4.0`
7.3	4.x	⚠️ security only	`composer require mjaschen/phpgeo:^4.0`
7.2	3.x	❌ end of life	`composer require mjaschen/phpgeo:^3.0`
7.1	2.x	❌ end of life	`composer require mjaschen/phpgeo:^2.0`
7.0	2.x	❌ end of life	`composer require mjaschen/phpgeo:^2.0`
5.6	1.x	❌ end of life	`composer require mjaschen/phpgeo:^1.0`
5.5	1.x	❌ end of life	`composer require mjaschen/phpgeo:^1.0`
5.4	1.x	❌ end of life	`composer require mjaschen/phpgeo:^1.0`

Documentation

The documentation is available at phpgeo.marcusjaschen.de., _(*6)

Installation

Using Composer, just add it to your composer.json by running:, _(*7)

composer require mjaschen/phpgeo

Upgrading

Update the version constraint in the project's composer.json and run composer update or require the new version by running:, _(*8)

composer require mjaschen/phpgeo:^6.0

Upgrading to 6.x

phpgeo has some breaking changes in the 6.x release line. Please refer to the following list to see what has changed and what you need to do to upgrade your code., _(*9)

Change	Description	Action
`Line`, `Polygon`, and `Polyline` classes are now implementing a new interface	`GeometryLinesInterface` provides the `getSegments()` method.	There's no need to change anything if you don't extend those classes.
`getBounds()` method was added to `GeometryInterface`		Ensure your class has a `getBounds()` method if you implement `GeometryInterface`
removed support for PHP 8.1	Older PHP versions are no longer supported.	Upgrade to at least PHP 8.2 or keep using phpgeo 5.x

Upgrading to 5.x

phpgeo has some breaking changes in the 5.x release line. Please refer to the following list to see what has changed and what you need to do to upgrade your code., _(*10)

Change	Description	Action
`setPoint1()` and `setPoint2()` methods removed from `Line`	The `Line` class now is immutable.	Use the constructor to create a new instance of `Line`.
removed support for PHP 7.3, 7.4 and 8.0	Older PHP versions are no longer supported.	Upgrade to at least PHP 8.1.

License

Starting with version 2.0.0 phpgeo is licensed under the MIT license. Older versions were GPL-licensed., _(*11)

Features

Info: Please visit the documentation site for complete and up-to-date documentation with many examples!, _(*12)

phpgeo provides the following features (follow the links for examples):, _(*13)

abstractions of several geometry objects (coordinate/point, line, polyline/GPS track, polygon
support for different ellipsoids, e.g. WGS-84
length/distance/perimeter calculations with different implementations (Haversine, Vincenty)
Geofence calculation, i.e. answering the question "Is this point contained in that area/polygon?" and other intersection checks between different geometries
formatting and output of geometry objects (GeoJSON, nice strings, e. g. 18° 54′ 41″ -155° 40′ 42″)
calculation of bearing angle between two points (spherical or with Vincenty's formula)
calculation of a destination point for a given starting point, bearing angle, and distance (spherical or with Vincenty's formula)
calculation of the perpendicular distance between a point and a line
calculation of the Cardinal Distances between two points
getting segments of a polyline /polygon,
reversing direction of polyline/polygon

Examples/Usage

This list is incomplete, please visit the documentation site for the full monty of documentation and examples!, _(*14)

Distance between two coordinates (Vincenty's Formula)

Use the calculator object directly:, _(*15)

<?php

use Location\Coordinate;
use Location\Distance\Vincenty;

$coordinate1 = new Coordinate(19.820664, -155.468066); // Mauna Kea Summit
$coordinate2 = new Coordinate(20.709722, -156.253333); // Haleakala Summit

$calculator = new Vincenty();

echo $calculator->getDistance($coordinate1, $coordinate2); // returns 128130.850 (meters; ≈128 kilometers)

or call the getDistance() method of a Coordinate object by injecting a calculator object:, _(*16)

<?php

use Location\Coordinate;
use Location\Distance\Vincenty;

$coordinate1 = new Coordinate(19.820664, -155.468066); // Mauna Kea Summit
$coordinate2 = new Coordinate(20.709722, -156.253333); // Haleakala Summit

echo $coordinate1->getDistance($coordinate2, new Vincenty()); // returns 128130.850 (meters; ≈128 kilometers)

Simplifying a polyline

Polylines can be simplified to save storage space or bandwidth. Simplification is done with the Ramer–Douglas–Peucker algorithm (AKA Douglas-Peucker algorithm)., _(*17)

<?php

use Location\Coordinate;
use Location\Polyline;
use Location\Distance\Vincenty;

$polyline = new Polyline();
$polyline->addPoint(new Coordinate(10.0, 10.0));
$polyline->addPoint(new Coordinate(20.0, 20.0));
$polyline->addPoint(new Coordinate(30.0, 10.0));

$processor = new Simplify($polyline);

// remove all points which perpendicular distance is less
// than 1500 km from the surrounding points.
$simplified = $processor->simplify(1500000);

// simplified is the polyline without the second point (which
// perpendicular distance is ~1046 km and therefore below
// the simplification threshold)

Polygon contains a point (e.g. "GPS geofence")

phpgeo has a polygon implementation which can be used to determinate if a point is contained in it or not. A polygon consists of at least three points. Points are instances of the Coordinate class., _(*18)

Warning: The calculation gives wrong results if the polygons has points on both sides of the 180/-180 degrees meridian., _(*19)

<?php

use Location\Coordinate;
use Location\Polygon;

$geofence = new Polygon();

$geofence->addPoint(new Coordinate(-12.085870,-77.016261));
$geofence->addPoint(new Coordinate(-12.086373,-77.033813));
$geofence->addPoint(new Coordinate(-12.102823,-77.030938));
$geofence->addPoint(new Coordinate(-12.098669,-77.006476));

$outsidePoint = new Coordinate(-12.075452, -76.985079);
$insidePoint = new Coordinate(-12.092542, -77.021540);

var_dump($geofence->contains($outsidePoint)); // returns bool(false) the point is outside the polygon
var_dump($geofence->contains($insidePoint)); // returns bool(true) the point is inside the polygon

Formatted output of coordinates

You can format a coordinate in different styles., _(*20)

Decimal Degrees

<?php

use Location\Coordinate;
use Location\Formatter\Coordinate\DecimalDegrees;

$coordinate = new Coordinate(19.820664, -155.468066); // Mauna Kea Summit

echo $coordinate->format(new DecimalDegrees());

Degrees/Minutes/Seconds (DMS)

<?php

use Location\Coordinate;
use Location\Formatter\Coordinate\DMS;

$coordinate = new Coordinate(18.911306, -155.678268); // South Point, HI, USA

$formatter = new DMS();

echo $coordinate->format($formatter); // 18° 54′ 41″ -155° 40′ 42″

$formatter->setSeparator(", ")
    ->useCardinalLetters(true)
    ->setUnits(DMS::UNITS_ASCII);

echo $coordinate->format($formatter); // 18° 54' 41" N, 155° 40' 42" W

GeoJSON

<?php

use Location\Coordinate;
use Location\Formatter\Coordinate\GeoJSON;

$coordinate = new Coordinate(18.911306, -155.678268); // South Point, HI, USA

echo $coordinate->format(new GeoJSON()); // { "type" : "point" , "coordinates" : [ -155.678268, 18.911306 ] }

Development

Run Tests

Before submitting a pull request, please be sure to run all checks and tests and ensure everything is green., _(*21)

lint PHP files for syntax errors: composer ci:lint
run static analysis with [Psalm][] and report errors: composer ci:psalm
run unit tests with PHPUnit: composer ci:tests

To run all checks and tests at once, just use composer ci., _(*22)

Of course, it's possible to use the test runners directly, e.g. for PHPUnit:, _(*23)

./vendor/bin/phpunit

PHPStan:, _(*24)

./vendor/bin/phpstan

Running GitHub Actions locally

It's possible to run the whole CI test matrix locally with act:, _(*25)

act --rm -P ubuntu-latest=shivammathur/node:latest

Credits

Marcus Jaschen mail@marcusjaschen.de and all contributors
Chris Veness - JavaScript implementation of the Vincenty formula for distance calculation
Ersts,P.J., Horning, N., and M. Polin[Internet] Perpendicular Distance Calculator(version 1.2.2) Documentation. American Museum of Natural History, Center for Biodiversity and Conservation. Available from http://biodiversityinformatics.amnh.org/open_source/pdc. Accessed on 2013-07-07.
W. Randolph Franklin, PNPOLY - Point Inclusion in Polygon Test Documentation

The Versions

19/07 2018

dev-master

9999999-dev https://phpgeo.marcusjaschen.de/

Simple Geo Library

library phpgeo

Simple Geo Library

mjaschen/phpgeo

The README.md

phpgeo - A Simple Geo Library for PHP

Requirements

Documentation

Installation

Upgrading

Upgrading to 6.x

Upgrading to 5.x

License

Features

Examples/Usage

Distance between two coordinates (Vincenty's Formula)

Simplifying a polyline

Polygon contains a point (e.g. "GPS geofence")

Formatted output of coordinates

Decimal Degrees

Degrees/Minutes/Seconds (DMS)

GeoJSON

Development

Run Tests

Running GitHub Actions locally

Credits

The Versions

dev-master

The Requires

The Development Requires

by Marcus Jaschen

2.0.3

The Requires

The Development Requires

by Marcus Jaschen

dev-feat_static_analyzer

The Requires

The Development Requires

by Marcus Jaschen

2.0.2

The Requires

The Development Requires

by Marcus Jaschen

2.0.1

The Requires

The Development Requires

by Marcus Jaschen

dev-add-code-of-conduct-1

The Requires

The Development Requires

by Marcus Jaschen

2.0.0

The Requires

The Development Requires

by Marcus Jaschen

dev-develop

The Requires

The Development Requires

by Marcus Jaschen

1.3.8

The Requires

The Development Requires

by Marcus Jaschen

1.3.7

The Requires

The Development Requires

by Marcus Jaschen

dev-develop-1.0

The Requires

The Development Requires

by Marcus Jaschen

1.3.6

The Requires

The Development Requires

by Marcus Jaschen

1.3.5

The Requires

The Development Requires

by Marcus Jaschen

1.3.4

The Requires