Calculate the distance between coordinates.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
tests
.gitignore
README.md
composer.json
example.php
phpcs.xml
phpmd.xml
phpstan.neon
phpunit.xml

README.md

Introduction

Calculate the distance between coordinates.

Build Status Scrutinizer Code Quality Code Coverage SensioLabsInsight

This package uses the UnitAngle and UnitLength classes from nmarfurt/measurements. Further, resulting measurements, like distance, are represented by a Measurement. To make full use of this library, it is recommended to familiarize oneself with that package first.

Installation

composer require zero-config/geo-distance

Procedural approach

To use the data models for coordinates and distance calculation in a procedural manner, try the following:

<?php
use function ZeroConfig\GeoDistance\coordinates;
use function ZeroConfig\GeoDistance\distance;

// Returns a distance of approximately 361 kilometers.
// The distance function uses the distance calculator under the hood.
// It assumes earth as base sphere for calculations.
echo distance(
    coordinates(50.0, 5.0),
    coordinates(53.0, 3.0)
) . PHP_EOL;

coordinates

The coordinates function accepts:

  • float $latitude
  • float $longitude

Both are a number representing an angle in degrees.

It returns an instance of:

ZeroConfig\GeoDistance\PositionInterface

<?php
use function ZeroConfig\GeoDistance\coordinates;

// This outputs: 50.6 °
echo coordinates(50.6, 5.0)->getLatitude() . PHP_EOL;

distance

The distance function accepts:

  • ZeroConfig\GeoDistance\PositionInterface $start
  • ZeroConfig\GeoDistance\PositionInterface $end

Both are positions on a sphere.

It returns an instance of:

Measurements\Measurement

<?php
use function ZeroConfig\GeoDistance\coordinates;
use function ZeroConfig\GeoDistance\distance;
use Measurements\Units\UnitLength;

// Outputs: 36113.471850273 dam
echo distance(
    coordinates(50.0, 5.0),
    coordinates(53.0, 3.0)
)->convertTo(UnitLength::decameters()) . PHP_EOL;

Object oriented approach

The following data models exist:

  • Position, combined latitude and longitude
  • Sphere, the object on which coordinates are plotted when calculating distance
<?php
use ZeroConfig\GeoDistance\ConvertedDistanceCalculator;
use ZeroConfig\GeoDistance\DistanceCalculator;
use ZeroConfig\GeoDistance\Position;
use ZeroConfig\GeoDistance\Sphere\CelestialBody\Mars;
use Measurements\Units\UnitLength;

$marsDistanceCalculator = new ConvertedDistanceCalculator(
    new DistanceCalculator(new Mars()),
    UnitLength::kilometers()
);

// On Mars, the same coordinates as on earth, give a distance of only 192 kilometers.
echo $marsDistanceCalculator->calculate(
    Position::create(50.0, 5.0),
    Position::create(53.0, 3.0)
) . PHP_EOL;