phpgeo

https://github.com/mjaschen/phpgeo
Admin
A PHP library for geographical coordinate calculations, providing abstractions for geometry objects,...
Tokens:49,631
Snippets:392
Trust Score:10
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://github.com/mjaschen/phpgeo/blob/main/CONTRIBUTING.md

Install project dependencies using Composer.

```bash
composer install
```

--------------------------------

### Preview documentation locally

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/020_Development.md

Starts a local server with live reload for previewing the documentation site.

```shell
make serve-docs
```

--------------------------------

### Install phpgeo via Composer

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/010_Installation.md

Use Composer to require the phpgeo package. This installs the latest compatible version for your PHP environment.

```shell
composer require mjaschen/phpgeo
```

--------------------------------

### Install documentation dependencies with uv

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/020_Development.md

Installs locked dependencies for the documentation project using uv.

```shell
uv sync --directory documentation --frozen
```

--------------------------------

### Output of Ellipsoid Creation Example

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/300_Ellipsoid.md

Expected output from the preceding PHP example, showing the computed semi-minor axis b and inverse flattening 1/f for the default WGS-84 and custom GRS-80 ellipsoids.

```plaintext
WGS-84: a=6378137.000000; b=6356752.314245; 1/f=298.257224
GRS-80: a=6378137.000000; b=6356752.314133; 1/f=298.257222

```

--------------------------------

### Expected output for hasSameLocation comparison

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/300_Comparisons/310_Same_Point_Comparison.md

Shows the exact output produced by the PHP example above. The first line indicates the two summits are different, and the second line confirms the telescope is within the 1 km radius.

```plaintext
Mauna Kea and Haleakala have different locations.
Mauna Kea and the Gemini North Telescope are located within the same 1 km-radius.
```

--------------------------------

### Create Ellipsoid by Default Name and Custom Parameters

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/300_Ellipsoid.md

Shows how to instantiate an Ellipsoid using the default 'WGS-84' configuration via Ellipsoid::createDefault() and a custom 'GRS-80' ellipsoid via the constructor with name, semi-major axis a, and inverse flattening 1/f. The output prints name, a, b, and 1/f for both ellipsoids.

```php
<?php

use Location\Ellipsoid;

$ellipsoid = Ellipsoid::createDefault('WGS-84');

printf(
    "%s: a=%f; b=%f; 1/f=%f\n",
    $ellipsoid->getName(),
    $ellipsoid->getA(),
    $ellipsoid->getB(),
    $ellipsoid->getF()
);

$ellipsoid = new Ellipsoid('GRS-80', 6378137, 298.257222);

printf(
    "%s: a=%f; b=%f; 1/f=%f\n",
    $ellipsoid->getName(),
    $ellipsoid->getA(),
    $ellipsoid->getB(),
    $ellipsoid->getF()
);

```

--------------------------------

### Get Intermediate Point at Fraction

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/120_Line.md

Divides the line at a given fraction (0.25) and formats the resulting coordinate using DecimalMinutes. Outputs the formatted coordinate.

```php
<?php

declare(strict_types=1);

use Location\Coordinate;
use Location\Formatter\Coordinate\DecimalMinutes;
use Location\Line;

$line = new Line(
    new Coordinate(0, 0),
    new Coordinate(1, 1)
);

$result = $line->getIntermediatePoint(0.25);

printf(
    'The first quarter of the line ends at %s%s',
    $result->format(new DecimalMinutes(' ')),
    PHP_EOL
);
```

```plaintext
The first quarter of the line ends at 00° 15.001′ 000° 14.999′
```

--------------------------------

### Format coordinate as Degrees/Minutes/Seconds (DMS)

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Formats a coordinate in degrees/minutes/seconds style using the DMS formatter. Shows default output and customization with setSeparator(), useCardinalLetters(), and setUnits(DMS::UNITS_ASCII). The example formats the South Point, HI, USA coordinate.

```php
<?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
```

--------------------------------

### Format coordinate as Decimal Degrees

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Formats a coordinate in decimal degrees style using the DecimalDegrees formatter. The example formats the Mauna Kea Summit coordinate.

```php
<?php

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

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

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

--------------------------------

### Get list of points with getPoints() and getNumberOfPoints()

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/140_Polygon.md

Retrieves the polygon's points and count, formatting each point with the DMS formatter. Output shows 3 points with DMS coordinates.

```php
<?php

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

$polygon = new Polygon();
$polygon->addPoint(new Coordinate(52.5, 13.5));
$polygon->addPoint(new Coordinate(54.5, 12.5));
$polygon->addPoint(new Coordinate(55.5, 14.5));

printf("The polygon consists of %d points:\n", $polygon->getNumberOfPoints());

foreach ($polygon->getPoints() as $point) {
    echo $point->format(new DMS()) . PHP_EOL;
}
?>
```

```plaintext
The polygon consists of 3 points:
52° 30′ 00″ 013° 30′ 00″
54° 30′ 00″ 012° 30′ 00″
55° 30′ 00″ 014° 30′ 00″
```

--------------------------------

### Format coordinate as GeoJSON

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Formats a coordinate as a GeoJSON point using the GeoJSON formatter. The example formats the South Point, HI, USA coordinate and outputs a JSON object with type 'point' and coordinates array.

```php
<?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 ] }
```

--------------------------------

### Compare two coordinates with hasSameLocation and optional error margin

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/300_Comparisons/310_Same_Point_Comparison.md

Checks whether two Location\Coordinate instances describe the same location using hasSameLocation(). The optional second argument sets an allowed error margin in meters; without it, exact equality is required. The example compares Mauna Kea Summit with Haleakala Summit (no margin) and with Gemini North Telescope (1000 m margin), printing a message for each case.

```php
<?php

use Location\Coordinate;

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

echo $coordinate1->hasSameLocation($coordinate2)
    ? 'Mauna Kea and Haleakala share the same location.'
    : 'Mauna Kea and Haleakala have different locations.';

$coordinate1 = new Coordinate(19.820664, -155.468066); // Mauna Kea Summit
$coordinate2 = new Coordinate(19.82365, -155.46905); // Gemini North Telescope

echo $coordinate1->hasSameLocation($coordinate2, 1000)
    ? 'Mauna Kea and the Gemini North Telescope are located within the same 1 km-radius.'
    : 'Mauna Kea and the Gemini North Telescope are located more than 1 km apart.';
```

--------------------------------

### Get polygon segments with getSegments()

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/140_Polygon.md

Iterates over the polygon's segments (Line instances) and prints each length in meters using the Haversine distance. Output shows three segment lengths.

```php
<?php

use Location\Coordinate;
use Location\Distance\Haversine;
use Location\Polygon;

$polygon = new Polygon();
$polygon->addPoint(new Coordinate(52.5, 13.5));
$polygon->addPoint(new Coordinate(54.5, 12.5));
$polygon->addPoint(new Coordinate(55.5, 14.5));

foreach ($polygon->getSegments() as $line) {
    printf("%0.3f m\n", $line->getLength(new Haversine()));
}
?>
```

```plaintext
232011.020 m
169207.795 m
339918.069 m
```

--------------------------------

### Distance between two coordinates using Coordinate::getDistance()

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Calculates the distance between two coordinates by injecting a Vincenty calculator object into the getDistance() method of a Coordinate object. Returns the distance in meters (approximately 128130.850 meters for the example coordinates).

```php
<?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)
```

--------------------------------

### Calculate final bearing for a calculated destination

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/420_Bearing_and_Destination.md

Uses BearingEllipsoidal to calculate the final bearing angle for a given start point, initial bearing, and distance. Outputs the final bearing value.

```php
<?php
use Location\Bearing\BearingEllipsoidal;
use Location\Coordinate;
use Location\Formatter\Coordinate\DecimalDegrees;

$berlin = new Coordinate(52.5, 13.5);

$bearingEllipsoidal = new BearingEllipsoidal();

$finalBearing = $bearingEllipsoidal->calculateDestinationFinalBearing($berlin, 153, 56100);

var_dump($finalBearing);
```

```plaintext
float(153.29365182147)
```

--------------------------------

### Calculate destination point for given bearing and distance

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/420_Bearing_and_Destination.md

Starting from Berlin, calculates destination point 56.1 km away with initial bearing 153 degrees using both spherical and ellipsoidal models. Outputs formatted coordinates.

```php
<?php
use Location\Bearing\BearingEllipsoidal;
use Location\Bearing\BearingSpherical;
use Location\Coordinate;
use Location\Formatter\Coordinate\DecimalDegrees;

$berlin = new Coordinate(52.5, 13.5);

$bearingSpherical = new BearingSpherical();
$bearingEllipsoidal = new BearingEllipsoidal();

$destination1 = $BearingSpherical->calculateDestination($berlin, 153, 56100);
$destination2 = $bearingEllipsoidal->calculateDestination($berlin, 153, 56100);

echo "Spherical:   " . $destination1->format(new DecimalDegrees()) . PHP_EOL;
echo "Ellipsoidal: " . $destination2->format(new DecimalDegrees()) . PHP_EOL;
```

```plaintext
Spherical:   52.04988 13.87628
Ellipsoidal: 52.05020 13.87126
```

--------------------------------

### Simplify a polyline using Ramer-Douglas-Peucker algorithm

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Simplifies a polyline to save storage space or bandwidth using the Ramer-Douglas-Peucker algorithm. The simplify() method removes points whose perpendicular distance is less than the given threshold (1500000 meters in this example). The resulting polyline omits the second point because its perpendicular distance (~1046 km) is below the threshold.

```php
<?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)
```

--------------------------------

### Calculate distance from point to line using PointToLineDistance

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/435_Distance_Between_Point_and_Line.md

Computes the shortest distance between a point and a Line using the PointToLineDistance utility with the Vincenty distance calculator. The example creates a point and a line, then prints the distance in meters. Output is 'Distance from point to line: 27164.1 meters'.

```php
<?php

use Location\Coordinate;
use Location\Distance\Vincenty;
use Location\Line;
use Location\Utility\PointToLineDistance;

$point = new Coordinate(52.5, 13.5);
$line = new Line(
    new Coordinate(52.5, 13.1),
    new Coordinate(52.5, 13.1)
);

$pointToLineDistanceCalculator = new PointToLineDistance(new Vincenty());

printf(
    'Distance from point to line: %.1f meters%s',
    $pointToLineDistanceCalculator->getDistance($point, $line),
    PHP_EOL
);

```

```plaintext
Distance from point to line: 27164.1 meters

```

--------------------------------

### Calculate Cardinal Distances using Coordinate method

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/425_Cardinal_Distance.md

Uses the getCardinalDirectionDistances() method on a Coordinate instance with Vincenty. Also gets the cardinal direction via CardinalDirection. Outputs direction and distances in meters.

```php
<?php

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

$point1 = new Coordinate(52.5072, 13.4248); // Berlin, Germany
$point2 = new Coordinate(52.4284, 13.0276); // Potsdam, Germany

$direction = (new CardinalDirection())->getCardinalDirection($point1, $point2);

$result = $point1->getCardinalDirectionDistances($point2, new Vincenty());

echo 'Cardinal Distances: direction=' . $direction
    . '; north=' . $result->getNorth()
    . ' m; east=' . $result->getEast()
    . ' m; south=' . $result->getSouth()
    . ' m; west=' . $result->getWest() . ' m.';

```

```text
Cardinal Distances: direction=north-east; north=0 m; east=0 m; south=8768.566 m; west=26969.504 m.

```

--------------------------------

### Distance between two coordinates using Vincenty calculator object

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Calculates the distance between two coordinates using the Vincenty formula via the calculator object directly. Returns the distance in meters (approximately 128130.850 meters for the example coordinates).

```php
<?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)
```

--------------------------------

### Check if a polygon contains a point (GPS geofence)

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Determines if a point is inside a polygon, useful for GPS geofencing. A polygon must have at least three points, each an instance of the Coordinate class. Warning: results are incorrect if the polygon has points on both sides of the 180/-180 degrees meridian. The example shows contains() returning false for an outside point and true for an inside point.

```php
<?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
```

--------------------------------

### Determine cardinal direction between points using Direction class

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/300_Comparisons/320_Directions.md

Uses the Direction class to check if one point is north or east of another. The example compares Helsinki, Berlin, and Rome coordinates and prints the results. Output shows Helsinki is north of Berlin and Berlin is east of Rome.

```php
<?php

use Location\Coordinate;

$berlin = new Coordinate(52.5, 13.5);
$rome = new Coordinate(42, 12.5);
$helsinki = new Coordinate(60, 25);

$direction = new Direction();

if ($direction->pointIsNorthOf(point: $helsinki, compareAgainst: $berlin)) {
  echo 'Helsinki is located north of Berlin.' . PHP_EOL;
}  else {
  echo 'Berlin is located north of Helsinki.' . PHP_EOL;
}

if ($direction->pointIsEastOf(point: $rome, compareAgainst: $berlin)) {
  echo 'Rome is located east of Berlin.' . PHP_EOL;
}  else {
  echo 'Berlin is located east of Rome.' . PHP_EOL;
}
```

```plaintext
Helsinki is located north of Berlin.
Berlin is located east of Rome.
```

--------------------------------

### Run tests

Source: https://github.com/mjaschen/phpgeo/blob/main/CONTRIBUTING.md

Run the test suite with Composer.

```bash
composer ci
```

--------------------------------

### Generate documentation with Makefile

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/020_Development.md

Builds the complete documentation using the Makefile helper target.

```shell
make docs
```

--------------------------------

### Run GitHub Actions locally with act

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Use this command to run the entire CI test matrix locally using act. The -rm flag removes containers after execution, and -P maps ubuntu-latest to a PHP-enabled image.

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

--------------------------------

### Run PHPUnit directly

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/020_Development.md

Executes PHPUnit directly from the vendor directory.

```shell
./vendor/bin/phpunit
```

--------------------------------

### Checkout feature branch

Source: https://github.com/mjaschen/phpgeo/blob/main/CONTRIBUTING.md

Create and switch to a new branch for your changes.

```bash
git checkout -b fix-random-bug
```

--------------------------------

### Calculate Initial Bearing with BearingEllipsoidal

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/120_Line.md

Calculates the initial bearing of a line using the BearingEllipsoidal class. Outputs the bearing in degrees.

```php
<?php

use Location\Bearing\BearingEllipsoidal;
use Location\Coordinate;
use Location\Line;

$line = new Line(
    new Coordinate(52.5, 13.5),
    new Coordinate(52.6, 13.4)
);

$bearing = $line->getBearing(new BearingEllipsoidal());

printf("The line has a bearing of %.2f degrees\n", $bearing);
```

```plaintext
The line has a bearing of 328.67 degrees
```

--------------------------------

### Push to fork

Source: https://github.com/mjaschen/phpgeo/blob/main/CONTRIBUTING.md

Push the branch to your fork and set upstream.

```bash
git push --set-upstream origin fix-random-bug
```

--------------------------------

### Run unit tests via Composer

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/020_Development.md

Runs the phpgeo unit test suite using the Composer script wrapper.

```shell
composer ci:tests
```

--------------------------------

### Run PHPStan static analysis directly

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Use this command to run PHPStan static analysis directly without the Composer wrapper. It analyzes the codebase for potential errors.

```shell
./vendor/bin/phpstan
```

--------------------------------

### Parse coordinate string with CoordinateFactory::fromString

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/700_Parsing_and_Input/110_Coordinates_Parser.md

Uses the CoordinateFactory to parse a coordinate string in decimal minutes format and formats the result as decimal degrees. Requires the phpgeo autoloader. The example outputs '52.22830 20.97560'.

```php
use Location\Factory\CoordinateFactory;
use Location\Formatter\Coordinate\DecimalDegrees;

require_once __DIR__ . '/vendor/autoload.php';

$point = CoordinateFactory::fromString('52° 13.698′ 020° 58.536′');

echo $point->format(new DecimalDegrees());
```

```plaintext
  52.22830 20.97560
```

--------------------------------

### Run tests with Docker using PHP 8.3

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/020_Development.md

Runs the test suite inside a Docker container with PHP 8.3 CLI.

```shell
docker run -it --rm --name phpgeo-phpunit \
    -v "$PWD":/usr/src/phpgeo \
    -w /usr/src/phpgeo php:8.3-cli \
    php vendor/bin/phpunit
```

--------------------------------

### Calculate perpendicular distance between a point and a line

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/430_Perpendicular_Distance.md

Uses the PerpendicularDistance utility class to compute the shortest distance from a Coordinate to a Line (defined by two coordinates) on a spherical surface. The example prints the result in meters with one decimal place.

```php
<?php

use Location\Coordinate;
use Location\Line;
use Location\Utility\PerpendicularDistance;

$point = new Coordinate(52.44468, 13.57455);
$line = new Line(
    new Coordinate(52.4554, 13.5582),
    new Coordinate(52.4371, 13.5623)
);

$pdCalc = new PerpendicularDistance();

printf(
    "perpendicular distance: %.1f meters\n",
    $pdCalc->getPerpendicularDistance($point, $line)
);
```

```plaintext
perpendicular distance: 936.7 meters
```

--------------------------------

### Polygon::__construct

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/140_Polygon.md

Creates a new Polygon instance. The polygon is initially empty and points can be added using addPoint().

```APIDOC
## Polygon::__construct

### Description
Creates a new Polygon instance. The polygon is initially empty and points can be added using addPoint().

### Method
Constructor

### Signature
`public function __construct()`

### Parameters
None

### Return Value
A new Polygon instance.

### Example
```php
$polygon = new Polygon();
```
```

--------------------------------

### Commit changes

Source: https://github.com/mjaschen/phpgeo/blob/main/CONTRIBUTING.md

Stage all changes and commit them.

```bash
git add -A -- . && git commit
```

--------------------------------

### Run CI tasks with multiple PHP versions

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/020_Development.md

Runs all CI tasks sequentially for PHP 8.2, 8.3, and 8.4 using Docker images from ghcr.io/mjaschen.

```shell
for PHP_VERSION in 8.2 8.3 8.4 ; do \
  docker run -it --rm -v "$PWD":/phpgeo -w /phpgeo \
  ghcr.io/mjaschen/php:${PHP_VERSION}-cli-mj composer ci || break ; \
done
```

--------------------------------

### Clone repository

Source: https://github.com/mjaschen/phpgeo/blob/main/CONTRIBUTING.md

Clone your fork of phpgeo using SSH.

```bash
git clone git@github.com:yourname/phpgeo.git
```

--------------------------------

### Create a polyline with addPoint()

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/130_Polyline.md

Instantiate the Polyline class and add Coordinate points using addPoint(). Points can be appended at any time.

```php
<?php

use Location\Coordinate;
use Location\Polyline;

$polyline = new Polyline();
$polyline->addPoint(new Coordinate(52.5, 13.5));
$polyline->addPoint(new Coordinate(54.5, 12.5));
$polyline->addPoint(new Coordinate(55.5, 14.5));
?>
```

--------------------------------

### Run PHPStan static analysis

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/020_Development.md

Runs PHPStan static code analysis via Composer script.

```shell
composer ci:phpstan
```

--------------------------------

### Run lint command

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/020_Development.md

Runs the lint command to check for syntax errors in the source code.

```shell
composer ci:lint
```

--------------------------------

### Create a polygon with addPoint

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/140_Polygon.md

Instantiates a Polygon and adds three Coordinate points. Points can be added at any time.

```php
<?php

use Location\Coordinate;
use Location\Polygon;

$polygon = new Polygon();
$polygon->addPoint(new Coordinate(52.5, 13.5));
$polygon->addPoint(new Coordinate(54.5, 12.5));
$polygon->addPoint(new Coordinate(55.5, 14.5));
?>
```

--------------------------------

### getBearing(BearingInterface $bearingCalculator): float

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/120_Line.md

Calculates the initial bearing of the line in degrees using the provided bearing calculation algorithm. The method expects an instance of a class implementing the BearingInterface, such as BearingEllipsoidal or BearingSpherical.

```APIDOC
## getBearing(BearingInterface $bearingCalculator): float

### Description
Calculates the initial bearing of the line in degrees using the provided bearing calculation algorithm.

### Method
`getBearing`

### Parameters
- **$bearingCalculator** (BearingInterface) - Required - An instance of a class implementing the BearingInterface (e.g., BearingEllipsoidal, BearingSpherical).

### Return Value
- **float** - The initial bearing in degrees.

### Example
```php
<?php

use Location\Bearing\BearingEllipsoidal;
use Location\Coordinate;
use Location\Line;

$line = new Line(
    new Coordinate(52.5, 13.5),
    new Coordinate(52.6, 13.4)
);

$bearing = $line->getBearing(new BearingEllipsoidal());

printf("The line has a bearing of %.2f degrees\n", $bearing);
```

### Output
```plaintext
The line has a bearing of 328.67 degrees
```
```

--------------------------------

### Upgrade phpgeo to a specific version

Source: https://github.com/mjaschen/phpgeo/blob/main/README.md

Updates the phpgeo package to version 6.0 or later. Use this command to upgrade to a new major version.

```shell
composer require mjaschen/phpgeo:^6.0
```

--------------------------------

### Calculate Final Bearing with BearingEllipsoidal

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/120_Line.md

Calculates the final bearing of a line using the BearingEllipsoidal class. Outputs the bearing in degrees.

```php
<?php

use Location\Bearing\BearingEllipsoidal;
use Location\Coordinate;
use Location\Line;

$line = new Line(
    new Coordinate(52.5, 13.5),
    new Coordinate(52.6, 13.4)
);

$bearing = $line->getFinalBearing(new BearingEllipsoidal());

printf("The line has a final bearing of %.2f degrees\n", $bearing);
```

```plaintext
The line has a final bearing of 328.59 degrees
```

--------------------------------

### Simplify polyline with Delta-Bearing algorithm

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/500_Transformations_and_Processing/510_Simplifying_a_Polyline_or_Polygon.md

Uses SimplifyBearing with a minimum angle of 90 degrees between adjacent segments. Points are removed when the bearing angle difference is less than the threshold. Outputs the simplified polyline's points in decimal degrees.

```php
<?php

use Location\Coordinate;
use Location\Formatter\Coordinate\DecimalDegrees;
use Location\Polyline;
use Location\Processor\Polyline\SimplifyBearing;

$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 SimplifyBearing(90);

$simplified = $processor->simplify($polyline);

foreach ($simplified->getPoints() as $point) {
    echo $point->format(new DecimalDegrees()) . PHP_EOL;
}

```

```plaintext
10.00000 10.00000
30.00000 10.00000

```

--------------------------------

### Calculate Line Length with Haversine

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/120_Line.md

Creates a Line from two Coordinate instances and calculates its length using the Haversine distance class. Outputs the length in meters.

```php
<?php

use Location\Coordinate;
use Location\Distance\Haversine;
use Location\Line;

$line = new Line(
    new Coordinate(52.5, 13.5),
    new Coordinate(52.6, 13.4)
);

$length = $line->getLength(new Haversine());

printf("The line has a length of %.3f meters\n", $length);
```

```plaintext
The line has a length of 13013.849 meters
```

--------------------------------

### Calculate bearing between two points using spherical earth model

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/420_Bearing_and_Destination.md

Uses BearingSpherical to calculate initial and final bearing between Berlin and London. Outputs bearing values and elapsed time.

```php
<?php

use Location\Bearing\BearingSpherical;
use Location\Coordinate;

$berlin = new Coordinate(52.5, 13.5);
$london = new Coordinate(51.5, -0.12);

$bearingCalculator = new BearingSpherical();

$startTime = microtime(true);
var_dump($bearingCalculator->calculateBearing($berlin, $london));
var_dump($bearingCalculator->calculateFinalBearing($berlin, $london));
$endTime = microtime(true);
printf("Time elapsed: %0.6f s\n", ($endTime - $startTime));
```

```plaintext
double(268.60722336693)
double(257.85494586285)
Time elapsed: 0.000285 s
```

--------------------------------

### Create Bounds from center coordinate and distance using BoundsFactory::expandFromCenterCoordinate

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/200_Bounds.md

Creates a Bounds object by expanding from a center Coordinate (52, 13) with a distance of 1000 meters, using a BearingSpherical calculator. The resulting bounds are defined by its north-eastern and south-western points.

```php
<?php

use Location\Factory\BoundsFactory;
use Location\Coordinate;

$bounds = BoundsFactory::expandFromCenterCoordinate(
    new Coordinate(52, 13),
    1000,
    new BearingSpherical()
);
```

--------------------------------

### Calculate bearing between two points using ellipsoidal earth model

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/420_Bearing_and_Destination.md

Uses BearingEllipsoidal to calculate initial and final bearing between Berlin and London. Outputs bearing values and elapsed time.

```php
<?php

use Location\Bearing\BearingEllipsoidal;
use Location\Coordinate;

$berlin = new Coordinate(52.5, 13.5);
$london = new Coordinate(51.5, -0.12);

$bearingCalculator = new BearingEllipsoidal();

$startTime = microtime(true);
var_dump($bearingCalculator->calculateBearing($berlin, $london));
var_dump($bearingCalculator->calculateFinalBearing($berlin, $london));
$endTime = microtime(true);
printf("Time elapsed: %0.6f s\n", ($endTime - $startTime));
```

```plaintext
double(268.62436347111)
double(257.87203657292)
Time elapsed: 0.000304 s
```

--------------------------------

### Calculate length of a polyline

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/410_Distance_and_Length.md

Builds a Polyline with at least two Coordinate points and calculates its length using the Vincenty distance calculator. Useful for GPS tracks or routes.

```php
<?php

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

$track = new Polyline();
$track->addPoint(new Coordinate(52.5, 13.5));
$track->addPoint(new Coordinate(54.5, 12.5));

echo $track->getLength(new Vincenty());
```

--------------------------------

### Polygon::getPoints

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/140_Polygon.md

Returns the list of points (Coordinate instances) that make up the polygon.

```APIDOC
## Polygon::getPoints

### Description
Returns the list of points (Coordinate instances) that make up the polygon.

### Method
`getPoints`

### Signature
`public function getPoints(): array`

### Parameters
None

### Return Value
An array of Coordinate objects.

### Example
```php
foreach ($polygon->getPoints() as $point) {
    echo $point->format(new DMS()) . PHP_EOL;
}
```
```

--------------------------------

### Reverse polyline direction with getReverse()

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/130_Polyline.md

Create a new Polyline instance with reversed point order while the original remains unchanged. The output shows the reversed object's structure.

```php
<?php

use Location\Coordinate;
use Location\Polyline;

$track = new Polyline();
$track->addPoint(new Coordinate(52.5, 13.5));
$track->addPoint(new Coordinate(54.5, 12.5));

$reversed = $track->getReverse();

print_r($reversed);
?>
```

```plaintext
Location\Polyline Object
(
    [points:protected] => Array
        (
            [0] => Location\Coordinate Object
                (
                    [lat:protected] => 54.5
                    [lng:protected] => 12.5
                    [ellipsoid:protected] => Location\Ellipsoid Object
                        (
                            [name:protected] => WGS-84
                            [a:protected] => 6378137
                            [f:protected] => 298.257223563
                        )

                )

            [1] => Location\Coordinate Object
                (
                    [lat:protected] => 52.5
                    [lng:protected] => 13.5
                    [ellipsoid:protected] => Location\Ellipsoid Object
                        (
                            [name:protected] => WGS-84
                            [a:protected] => 6378137
                            [f:protected] => 298.257223563
                        )

                )

        )

)
```

--------------------------------

### BoundsFactory::expandFromCenterCoordinate

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/200_Bounds.md

Creates a Bounds object for a given center coordinate and distance to the corners. The distance is measured from the center to each corner of the bounds.

```APIDOC
## BoundsFactory::expandFromCenterCoordinate

### Description
Creates a Bounds object for a given center coordinate and distance to the corners. The distance is measured from the center to each corner of the bounds.

### Method
`expandFromCenterCoordinate`

### Parameters
- **coordinate** (Coordinate) - Required - The center point of the bounds.
- **distance** (float) - Required - The distance from the center to each corner of the bounds.
- **bearing** (BearingSpherical) - Required - The bearing calculator used to compute the corner points.

### Return Value
- **Bounds** - The resulting bounds object.

### Example
```php
<?php

use Location\Factory\BoundsFactory;
use Location\Coordinate;

$bounds = BoundsFactory::expandFromCenterCoordinate(
    new Coordinate(52, 13),
    1000,
    new BearingSpherical()
);
```
```

--------------------------------

### Iterate over polyline segments with getSegments()

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/130_Polyline.md

Retrieve an array of Line instances representing the polyline segments. Each segment's length is calculated using the Haversine formula and printed in kilometers.

```php
<?php

use Location\Coordinate;
use Location\Polyline;

$track = new Polyline();
$track->addPoint(new Coordinate(52.5, 13.5));
$track->addPoint(new Coordinate(54.5, 12.5));
$track->addPoint(new Coordinate(55.5, 14.5));

foreach ($track->getSegments() as $segment) {
    printf(
        "Segment length: %0.2f kilometers\n",
        ($segment->getLength(new Haversine()) / 1000)
    );
}
?>
```

```plaintext
Segment length: 232.01 kilometers
Segment length: 169.21 kilometers
```

--------------------------------

### getFinalBearing(BearingInterface $bearingCalculator): float

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/120_Line.md

Calculates the final bearing of the line in degrees using the provided bearing calculation algorithm. The method expects an instance of a class implementing the BearingInterface, such as BearingEllipsoidal or BearingSpherical.

```APIDOC
## getFinalBearing(BearingInterface $bearingCalculator): float

### Description
Calculates the final bearing of the line in degrees using the provided bearing calculation algorithm.

### Method
`getFinalBearing`

### Parameters
- **$bearingCalculator** (BearingInterface) - Required - An instance of a class implementing the BearingInterface (e.g., BearingEllipsoidal, BearingSpherical).

### Return Value
- **float** - The final bearing in degrees.

### Example
```php
<?php

use Location\Bearing\BearingEllipsoidal;
use Location\Coordinate;
use Location\Line;

$line = new Line(
    new Coordinate(52.5, 13.5),
    new Coordinate(52.6, 13.4)
);

$bearing = $line->getFinalBearing(new BearingEllipsoidal());

printf("The line has a final bearing of %.2f degrees\n", $bearing);
```

### Output
```plaintext
The line has a final bearing of 328.59 degrees
```
```

--------------------------------

### getLength(DistanceInterface $distanceCalculator): float

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/120_Line.md

Calculates the length of the line in meters using the provided distance calculation algorithm. The method expects an instance of a class implementing the DistanceInterface, such as Haversine or Vincenty.

```APIDOC
## getLength(DistanceInterface $distanceCalculator): float

### Description
Calculates the length of the line in meters using the provided distance calculation algorithm.

### Method
`getLength`

### Parameters
- **$distanceCalculator** (DistanceInterface) - Required - An instance of a class implementing the DistanceInterface (e.g., Haversine, Vincenty).

### Return Value
- **float** - The length of the line in meters.

### Example
```php
<?php

use Location\Coordinate;
use Location\Distance\Haversine;
use Location\Line;

$line = new Line(
    new Coordinate(52.5, 13.5),
    new Coordinate(52.6, 13.4)
);

$length = $line->getLength(new Haversine());

printf("The line has a length of %.3f meters\n", $length);
```

### Output
```plaintext
The line has a length of 13013.849 meters
```
```

--------------------------------

### Calculate Cardinal Distances using Calculator Instance

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/425_Cardinal_Distance.md

Uses CardinalDirectionDistancesCalculator with Vincenty to compute cardinal distances between two coordinates. Outputs distances in meters for north, east, south, and west.

```php
<?php

use Location\Coordinate;
use Location\Distance\Vincenty;
use Location\CardinalDirection\CardinalDirectionDistancesCalculator;

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

$calculator = new Vincenty();
$cardinalDirectionDistancesCalculator = new CardinalDirectionDistancesCalculator();

$result = $cardinalDirectionDistancesCalculator->getCardinalDirectionDistances($coordinate1, $coordinate2, $calculator);

echo 'Cardinal Distances: north=' . $result->getNorth()
. ' m; east=' . $result->getEast()
. ' m; south=' . $result->getSouth(
. ' m; west=' . $result->getWest() . ' m.';

```

```text
Cardinal Distances: north=98425.507 m; east=0 m; south=0 m; west=82268.492 m.

```

--------------------------------

### Coordinate::getDistance(Coordinate $point, DistanceInterface $calculator)

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/400_Calculations/410_Distance_and_Length.md

Calculates the distance from this coordinate to another coordinate using the provided calculator. Returns the distance in meters.

```APIDOC
## Coordinate::getDistance(Coordinate $point, DistanceInterface $calculator)

### Description
Calculates the distance from this coordinate to another coordinate using the provided calculator. Returns the distance in meters.

### Method
`getDistance`

### Parameters
- **$point** (Coordinate) - Required - The target coordinate.
- **$calculator** (DistanceInterface) - Required - The distance calculator instance (e.g., Vincenty or Haversine).

### Return Value
- **float** - The distance in meters.

### Example
```php
<?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());
```

### Output
```plaintext
128130.850
```
```

--------------------------------

### Format polyline as GeoJSON with Location\Formatter\Polyline\GeoJSON

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/600_Formatting_and_Output/130_Polylines.md

Creates a polyline with two coordinates and formats it as a GeoJSON LineString. The output is affected by PHP's serialize_precision ini-setting, which controls the number of decimal places in the JSON output.

```php
<?php

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

$polyline = new Polyline;
$polyline->addPoint(new Coordinate(52.5, 13.5));
$polyline->addPoint(new Coordinate(62.5, 14.5));

$formatter = new GeoJSON;

echo $formatter->format($polyline);
```

```json
{"type":"LineString","coordinates":[[13.5,52.5],[14.5,62.5]]}
```

--------------------------------

### getIntermediatePoint(float $fraction): Coordinate

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/120_Line.md

Calculates a point along the line at the given fraction (between 0.0 and 1.0; values outside that range work as well). Returns a Coordinate instance representing the intermediate point.

```APIDOC
## getIntermediatePoint(float $fraction): Coordinate

### Description
Calculates a point along the line at the given fraction (between 0.0 and 1.0; values outside that range work as well).

### Method
`getIntermediatePoint`

### Parameters
- **$fraction** (float) - Required - The fraction along the line where the intermediate point should be located.

### Return Value
- **Coordinate** - The intermediate point on the line.

### Example
```php
<?php

declare(strict_types=1);

use Location\Coordinate;
use Location\Formatter\Coordinate\DecimalMinutes;
use Location\Line;

$line = new Line(
    new Coordinate(0, 0),
    new Coordinate(1, 1)
);

$result = $line->getIntermediatePoint(0.25);

printf(
    'The first quarter of the line ends at %s%s',
    $result->format(new DecimalMinutes(' ')),
    PHP_EOL
);
```

### Output
```plaintext
The first quarter of the line ends at 00° 15.001′ 000° 14.999′
```
```

--------------------------------

### Format coordinate as decimal minutes with default and ASCII units

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/600_Formatting_and_Output/100_Coordinates.md

Uses Location\Formatter\Coordinate\DecimalMinutes, commonly used in Geocaching. First output uses default separator and no cardinal letters; second uses comma-space separator, cardinal letters, and ASCII units. Outputs: '43° 37.386′ -070° 12.472′' and '43° 37.386' N, 070° 12.472' W'.

```php
<?php

use Location\Coordinate;
use Location\Formatter\Coordinate\DecimalMinutes;

$coordinate = new Coordinate(43.62310, -70.20787); // Portland Head Light, ME, USA

$formatter = new DecimalMinutes();

echo $coordinate->format($formatter) . PHP_EOL;

$formatter->setSeparator(', ')
    ->useCardinalLetters(true)
    ->setUnits(DecimalMinutes::UNITS_ASCII);

echo $coordinate->format($formatter) . PHP_EOL;
```

```plaintext
43° 37.386′ -070° 12.472′
43° 37.386' N, 070° 12.472' W
```

--------------------------------

### Polyline::getSegments()

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/130_Polyline.md

Returns an array of Line instances representing the segments between consecutive points in the polyline. Each segment can be used to calculate its length.

```APIDOC
## Polyline::getSegments()

### Description
Returns an array of Line instances representing the segments between consecutive points in the polyline. Each segment can be used to calculate its length.

### Method
getSegments

### Parameters
None

### Response
- **segments** (array of Line) - List of Line objects, each representing a segment between two consecutive points.

### Response Example
```php
foreach ($track->getSegments() as $segment) {
    printf("Segment length: %0.2f kilometers\n", ($segment->getLength(new Haversine()) / 1000));
}
```
```

--------------------------------

### Polyline::getReverse()

Source: https://github.com/mjaschen/phpgeo/blob/main/documentation/docs/100_Geometries/130_Polyline.md

Returns a new Polyline instance with the points in reverse order. The original polyline remains unchanged.

```APIDOC
## Polyline::getReverse()

### Description
Returns a new Polyline instance with the points in reverse order. The original polyline remains unchanged.

### Method
getReverse

### Parameters
None

### Response
- **polyline** (Polyline) - A new Polyline with reversed point order.

### Response Example
```php
$reversed = $track->getReverse();
print_r($reversed);
```
```
Tokens:
Raw