phpgeo

https://phpgeo.marcusjaschen.de/
Admin
A PHP library providing abstractions for geographical coordinates, polylines, polygons, bounds and...
Tokens:11,015
Snippets:125
Trust Score:8.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install phpgeo with Composer

Source: https://phpgeo.marcusjaschen.de/010_Installation

Use this command to install the latest version of phpgeo. Ensure you have Composer installed and configured for your project.

```bash
composer require mjaschen/phpgeo

```

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

### Geofence Output Example

Source: https://phpgeo.marcusjaschen.de/400_Calculations/440_Geofence

This is the expected output when running the PHP geofence checking code.

```text
Point 1 is located outside the polygon
Point 2 is located inside the polygon


```

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

### Define and Check Geofence with PHPGeo Polygon

Source: https://phpgeo.marcusjaschen.de/400_Calculations/440_Geofence

This snippet demonstrates how to create a geofence (polygon) by adding multiple coordinate points and then checking if two different points are inside or outside this geofence using the `contains` method. Ensure the Location library is installed and imported.

```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);

echo $geofence->contains($outsidePoint)
    ? 'Point 1 is located inside the polygon' . PHP_EOL
    : 'Point 1 is located outside the polygon' . PHP_EOL;

echo $geofence->contains($insidePoint)
    ? 'Point 2 is located inside the polygon' . PHP_EOL
    : 'Point 2 is located outside the polygon' . PHP_EOL;

```

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

### Calculate Destination Point (Spherical and Ellipsoidal)

Source: https://phpgeo.marcusjaschen.de/400_Calculations/420_Bearing_and_Destination

Calculate a destination coordinate from a starting point, bearing, and distance using both spherical and ellipsoidal models. Formats output in DecimalDegrees.

```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;

?>
```

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

### Get Polygon Points and Count

Source: https://phpgeo.marcusjaschen.de/100_Geometries/140_Polygon

Retrieve all points within a polygon using getPoints() and count them with getNumberOfPoints(). The points can be formatted for display.

```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;
}

?>
```

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

### Get Polygon Segments and Lengths

Source: https://phpgeo.marcusjaschen.de/100_Geometries/140_Polygon

Obtain polygon segments as Line instances and calculate their lengths using a specified distance calculation method.

```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()));
}

?>
```

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

### Get Polyline Segments

Source: https://phpgeo.marcusjaschen.de/100_Geometries/130_Polyline

Retrieve an array of Line instances representing the segments of the polyline. Each segment's length can then be calculated.

```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)
    );
}

?>
```

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

### Calculate Final Bearing for a Calculated Destination (Ellipsoidal)

Source: https://phpgeo.marcusjaschen.de/400_Calculations/420_Bearing_and_Destination

Determine the final bearing angle to a destination point using the ellipsoidal earth model, given a start point, initial bearing, and distance.

```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);

?>
```

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

### Generate Documentation with Makefile

Source: https://phpgeo.marcusjaschen.de/020_Development

Generate the complete documentation for the project using the Makefile helper target. This command is used for building the documentation site.

```bash
make docs

```

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

### Run Unit Tests with Composer

Source: https://phpgeo.marcusjaschen.de/020_Development

Execute the unit tests using the Composer script provided by phpgeo. This is the recommended way to run tests.

```bash
composer ci:tests

```

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

### Create and Inspect Ellipsoids

Source: https://phpgeo.marcusjaschen.de/100_Geometries/300_Ellipsoid

Demonstrates creating an Ellipsoid instance using a default configuration (WGS-84) and a custom configuration (GRS-80) by specifying the semi-major axis 'a' and the inverse flattening '1/f'. It also shows how to retrieve the ellipsoid's name, 'a', 'b', and '1/f' values.

```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()
);

?>
```

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

### Create a Polyline

Source: https://phpgeo.marcusjaschen.de/100_Geometries/130_Polyline

Instantiate the Polyline class and add points using the addPoint() method. Use addUniquePoint() to ensure points are not duplicated.

```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 All Tests with Composer

Source: https://phpgeo.marcusjaschen.de/020_Development

Execute all configured tests and CI tasks at once using a single Composer command. This is a convenient way to run the full test suite.

```bash
composer ci

```

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

### Run All CI Tasks with Different PHP Versions using Docker

Source: https://phpgeo.marcusjaschen.de/020_Development

Iterate through multiple PHP versions (8.2, 8.3, 8.4) and run all CI tasks for each version using Docker. The loop breaks if any task fails.

```bash
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

```

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

### Run Unit Tests with Docker and Specific PHP Version

Source: https://phpgeo.marcusjaschen.de/020_Development

Run the unit tests using Docker with a specific PHP version (e.g., PHP 8.3). This ensures tests are run in an isolated and consistent environment.

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

```

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

### Create Bounds from Center and Distance

Source: https://phpgeo.marcusjaschen.de/100_Geometries/200_Bounds

Creates a Bounds object by expanding from a given center coordinate with a specified distance. Requires importing the BoundsFactory and Coordinate classes.

```php
<?php

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

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


```

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

### Run Unit Tests Directly with PHPUnit

Source: https://phpgeo.marcusjaschen.de/020_Development

Execute the unit tests directly using the PHPUnit executable. This can be useful for specific testing scenarios.

```bash
./vendor/bin/phpunit

```

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

### Create a Polygon

Source: https://phpgeo.marcusjaschen.de/100_Geometries/140_Polygon

Instantiate a Polygon object and add Coordinate instances to define its vertices.

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

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

### Calculate Distance Between Point and Line in PHP

Source: https://phpgeo.marcusjaschen.de/400_Calculations/435_Distance_Between_Point_and_Line

Use the PointToLineDistance class to calculate the shortest distance between a point and a line. Ensure the Vincenty class is instantiated for distance calculations.

```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
);


```

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

### Calculate Cardinal Distances using Calculator Instance

Source: https://phpgeo.marcusjaschen.de/400_Calculations/425_Cardinal_Distance

Use this method when you need to calculate cardinal distances and have a separate calculator instance. It requires importing `Coordinate`, `Vincenty`, and `CardinalDirectionDistancesCalculator`.

```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.

```

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

### Run Static Code Analysis with PHPStan

Source: https://phpgeo.marcusjaschen.de/020_Development

Perform static code analysis using PHPStan. This command checks for potential errors and code quality issues.

```bash
composer ci:phpstan

```

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

### Run Linting Checks with Composer

Source: https://phpgeo.marcusjaschen.de/020_Development

Execute the lint command via Composer to ensure the sources do not contain any syntax errors. This is part of the static testing suite.

```bash
composer ci:lint

```

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

### Check Intersection Between Line and Polygon

Source: https://phpgeo.marcusjaschen.de/300_Comparisons/340_Intersections

Demonstrates how to check for intersections between a Line and a Polygon using the Intersection helper. It shows both a fast bounds check and a precise segment intersection check.

```PHP
use Location\Coordinate;
use Location\Intersection\Intersection;
use Location\Line;
use Location\Polygon;

$intersection = new Intersection();

$line = new Line(
    new Coordinate(52.237594, 9.287635),
    new Coordinate(52.258154, 11.010313)
);

$polygon = new Polygon();
$polygon->addPoint(new Coordinate(52.56571, 9.998658));
$polygon->addPoint(new Coordinate(52.369576, 9.560167));
$polygon->addPoint(new Coordinate(52.102252, 9.62397));
$polygon->addPoint(new Coordinate(51.983342, 10.132727));
$polygon->addPoint(new Coordinate(52.083498, 10.699142));
$polygon->addPoint(new Coordinate(52.457087, 10.590607));
$polygon->addPoint(new Coordinate(52.56571, 9.998658));

// Fast check: bounds intersection only (may return false positives).
$intersects = $intersection->intersects($line, $polygon, false);

// Precise check: segment intersections + containment.
$intersectsPrecisely = $intersection->intersects($line, $polygon, true);

```

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

### Calculate Initial Bearing of a Line

Source: https://phpgeo.marcusjaschen.de/100_Geometries/120_Line

Calculates the initial bearing of a line segment using the BearingEllipsoidal class. Requires Coordinate and Line instances.

```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);

?>
```

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

### Calculate Cardinal Distances using Coordinate Instance Method

Source: https://phpgeo.marcusjaschen.de/400_Calculations/425_Cardinal_Distance

This method is convenient for calculating cardinal distances directly from a Coordinate object. It requires importing `CardinalDirection`, `Coordinate`, and `Vincenty`.

```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.

```

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

### Calculate Intermediate Point on Line

Source: https://phpgeo.marcusjaschen.de/100_Geometries/120_Line

Calculates a point on the line segment at a specified fraction (0.0 to 1.0). Requires a Coordinate and Line instance.

```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
);

?>
```

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

### Calculate Distance Between Two Points (Vincenty's Formula)

Source: https://phpgeo.marcusjaschen.de/400_Calculations/410_Distance_and_Length

Use the Vincenty calculator directly to find the distance between two coordinates. Requires importing Coordinate and Vincenty classes.

```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);

?>
```

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

### Check Point Direction

Source: https://phpgeo.marcusjaschen.de/300_Comparisons/320_Directions

Use the Direction class to compare two coordinates and determine their relative north/east position. Ensure the Location\Coordinate and Location\Direction classes are imported.

```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;
}


```

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

### Simplify Polyline using Delta-Bearing Algorithm

Source: https://phpgeo.marcusjaschen.de/500_Transformations_and_Processing/510_Simplifying_a_Polyline_or_Polygon

Simplifies a polyline by removing points where the angle between adjacent segments is less than a specified threshold in degrees. This method is effective for smoothing out minor variations in direction.

```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;
}

?>
```

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

### Check Point-in-Polygon Intersection

Source: https://phpgeo.marcusjaschen.de/300_Comparisons/340_Intersections

Shows how to use the Intersection helper to determine if a Coordinate (point) is inside a Polygon. This requires a precise check.

```PHP
use Location\Coordinate;
use Location\Intersection\Intersection;
use Location\Polygon;

$intersection = new Intersection();
$point = new Coordinate(52.328745, 10.151638);
$intersects = $intersection->intersects($point, $polygon, true);

```

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

### Update phpgeo to v3.x

Source: https://phpgeo.marcusjaschen.de/015_Upgrading

Use this command to update phpgeo to version 3.x. Requires PHP 7.2 or higher.

```bash
composer require mjaschen/phpgeo:^3.0
```

```json
{
    "require": {
        "mjaschen/phpgeo": "^3.0"
    }
}
```

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

### Update phpgeo to v4.x

Source: https://phpgeo.marcusjaschen.de/015_Upgrading

Use this command to update phpgeo to version 4.x. Requires PHP 7.3 or higher.

```bash
composer require mjaschen/phpgeo:^4.0
```

```json
{
    "require": {
        "mjaschen/phpgeo": "^4.0"
    }
}
```

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

### Format Coordinate to Degrees/Minutes/Seconds (DMS)

Source: https://phpgeo.marcusjaschen.de/600_Formatting_and_Output/100_Coordinates

Formats a coordinate object into Degrees/Minutes/Seconds (DMS) format. This snippet shows the default format and a customized version with a comma separator, cardinal letters, and ASCII units.

```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) . PHP_EOL;

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

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

?>
```

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

### Calculate Distance Between Two Points (Vincenty's Formula) via Coordinate

Source: https://phpgeo.marcusjaschen.de/400_Calculations/410_Distance_and_Length

Calculate the distance between two coordinates by calling the getDistance() method on a Coordinate instance, injecting a Vincenty calculator. Requires importing Coordinate and Vincenty classes.

```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());

?>
```

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

### Calculate Distance Between Two Points (Haversine Formula)

Source: https://phpgeo.marcusjaschen.de/400_Calculations/410_Distance_and_Length

Calculate the distance between two coordinates using the Haversine formula, which is faster but less precise than Vincenty's method. Requires importing Coordinate and Haversine classes.

```php
<?php

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

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

echo $coordinate1->getDistance($coordinate2, new Haversine());

?>
```

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

### Simplify Polyline using Ramer-Douglas-Peucker Algorithm

Source: https://phpgeo.marcusjaschen.de/500_Transformations_and_Processing/510_Simplifying_a_Polyline_or_Polygon

Simplifies a polyline by removing points whose perpendicular distance to the line connecting surrounding points is less than a specified threshold in meters. This is useful for reducing data size while preserving the general shape of the polyline.

```php
<?php

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

$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 SimplifyDouglasPeucker(1500000);

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

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

?>
```

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

### Reverse Polyline Direction

Source: https://phpgeo.marcusjaschen.de/100_Geometries/130_Polyline

Obtain a new Polyline instance with the points in reverse order using the getReverse() method. The original polyline remains unchanged.

```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);

?>
```

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

### Update phpgeo to v5.x

Source: https://phpgeo.marcusjaschen.de/015_Upgrading

Use this command to update phpgeo to version 5.x. Ensure your PHP version is at least 8.1.

```bash
composer require mjaschen/phpgeo:^5.0
```

```json
{
    "require": {
        "mjaschen/phpgeo": "^5.0"
    }
}
```

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

### Reverse Polygon Direction

Source: https://phpgeo.marcusjaschen.de/100_Geometries/140_Polygon

Create a new polygon instance with the order of its vertices reversed. The original polygon remains unchanged.

```php
<?php

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

$polygon = new Polygon();
$polygon->addPoint(new Coordinate(52.5, 13.5));
$polygon->addPoint(new Coordinate(64.1, - 21.9));
$polygon->addPoint(new Coordinate(40.7, - 74.0));
$polygon->addPoint(new Coordinate(33.9, - 118.4));

$reversed = $polygon->getReverse();

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

?>
```

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

### Calculate Perimeter of a Polygon

Source: https://phpgeo.marcusjaschen.de/400_Calculations/410_Distance_and_Length

Calculate the perimeter of a polygon by summing the lengths of its segments. Requires importing Coordinate, Polygon, and a distance calculator like Vincenty.

```php
<?php

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

$polygon = new Polygon();
$polygon->addPoint(new Coordinate(10, 10));
$polygon->addPoint(new Coordinate(10, 20));
$polygon->addPoint(new Coordinate(20, 20));
$polygon->addPoint(new Coordinate(20, 10));

echo $polygon->getPerimeter(new Vincenty());

?>
```

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

### Format Coordinate to Decimal Degrees with Custom Separator and Decimals

Source: https://phpgeo.marcusjaschen.de/600_Formatting_and_Output/100_Coordinates

Formats a coordinate object into a string of decimal degrees with a custom separator (e.g., ', ') and a specified number of decimal places (e.g., 3).

```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(', ', 3));

?>
```

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

### Calculate Initial and Final Bearing (Spherical Model)

Source: https://phpgeo.marcusjaschen.de/400_Calculations/420_Bearing_and_Destination

Use BearingSpherical to find the initial and final bearing angles between two coordinates using a spherical earth model. Measures time elapsed for calculation.

```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));

?>
```

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

### Parse Coordinate String

Source: https://phpgeo.marcusjaschen.de/700_Parsing_and_Input/110_Coordinates_Parser

Use CoordinateFactory::fromString to parse a coordinate string in a supported format and format it as Decimal Degrees. Requires the Location library and autoloader.

```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());
```

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

### Format Coordinate to Decimal Degrees

Source: https://phpgeo.marcusjaschen.de/600_Formatting_and_Output/100_Coordinates

Formats a coordinate object into a string of decimal degrees. The default separator is a space and the default number of decimals is 5.

```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());

?>
```

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

### Calculate Line Midpoint

Source: https://phpgeo.marcusjaschen.de/100_Geometries/120_Line

Calculates the midpoint of a line segment by following the Great Circle. The result is a Coordinate object.

```php
<?php

declare(strict_types=1);

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

$line = new Line(
    new Coordinate(35, 45),
    new Coordinate(35, 135)
);

$midpoint = $line->getMidpoint();

printf(
    'The midpoint of the line is located at %.3f degrees latitude and %.3f degrees longitude.%s',
    $midpoint->getLat(),
    $midpoint->getLng(),
    PHP_EOL
);

printf(
    'Its distance from the first point is %.1f meters, its distance from the second point is %.1f meters.%s',
    $line->getPoint1()->getDistance($midpoint, new Haversine()),
    $line->getPoint2()->getDistance($midpoint, new Haversine()),
    PHP_EOL
);

?>
```

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

### Calculate Polygon Area and Perimeter

Source: https://phpgeo.marcusjaschen.de/100_Geometries/140_Polygon

Compute the area in square meters and the perimeter using specified distance calculations. Note that area calculation may have inaccuracies for large polygons.

```php
<?php

use Location\Coordinate;
use Location\Polygon;

$formatter = new \Location\Formatter\Coordinate\DecimalDegrees(' ', 10);

$polygon = new Polygon();
$polygon->addPoint(new Coordinate(0.0000000000, 0.0000000000));
$polygon->addPoint(new Coordinate(0.0000000000, 0.0008983153));
$polygon->addPoint(new Coordinate(0.0009043695, 0.0008983153));
$polygon->addPoint(new Coordinate(0.0009043695, 0.0000000000));

printf(
    'Polygon Area = %f m², Perimeter = %f m%s',
    $polygon->getArea(),
    $polygon->getPerimeter(new \Location\Distance\Vincenty()),
    PHP_EOL
);

?>
```

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

### Update phpgeo to v6.x

Source: https://phpgeo.marcusjaschen.de/015_Upgrading

Use this command to update phpgeo to version 6.x. Ensure your PHP version is at least 8.2.

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

```json
{
    "require": {
        "mjaschen/phpgeo": "^6.0"
    }
}
```

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

### Calculate Initial and Final Bearing (Ellipsoidal Model)

Source: https://phpgeo.marcusjaschen.de/400_Calculations/420_Bearing_and_Destination

Use BearingEllipsoidal to find the initial and final bearing angles between two coordinates using an ellipsoidal earth model. Measures time elapsed for calculation.

```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));

?>
```

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

### Format Polyline to GeoJSON

Source: https://phpgeo.marcusjaschen.de/600_Formatting_and_Output/130_Polylines

Use the GeoJSON formatter to convert a polyline object into a GeoJSON LineString format. Ensure the Location library and its GeoJSON formatter are imported.

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

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

### Comparing Two Points for Same Location

Source: https://phpgeo.marcusjaschen.de/300_Comparisons/310_Same_Point_Comparison

Compares two `Coordinate` objects to determine if they represent the exact same geographical location. Requires the `Location
ew Coordinate` class.

```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.';

```

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

### Calculate Line Length using Haversine

Source: https://phpgeo.marcusjaschen.de/100_Geometries/120_Line

Calculates the length of a line segment using the Haversine distance formula. Requires instances of Coordinate and Haversine.

```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);

?>
```

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

### Calculate Length of a Polyline

Source: https://phpgeo.marcusjaschen.de/400_Calculations/410_Distance_and_Length

Calculate the total length of a polyline (GPS track or route) by adding multiple Coordinate points. Requires importing Coordinate, Polyline, and a distance calculator like Vincenty.

```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());

?>
```

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

### Format Polygon to GeoJSON

Source: https://phpgeo.marcusjaschen.de/600_Formatting_and_Output/140_Polygons

Use the GeoJSON formatter to convert a Polygon object into a GeoJSON string. Ensure the 'serialize_precision' ini setting is considered for float output.

```php
<?php

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

$polygon = new Polygon;
$polygon->addPoint(new Coordinate(10, 20));
$polygon->addPoint(new Coordinate(20, 40));
$polygon->addPoint(new Coordinate(30, 40));
$polygon->addPoint(new Coordinate(30, 20));

$formatter = new GeoJSON;

echo $formatter->format($polygon);

?>
```

```json
{"type":"Polygon","coordinates":[[20,10],[40,20],[40,30],[20,30]]}
```

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

### Format Coordinate to Decimal Minutes

Source: https://phpgeo.marcusjaschen.de/600_Formatting_and_Output/100_Coordinates

Formats a coordinate object into Decimal Minutes format, commonly used in Geocaching. This snippet demonstrates the default format and a customized version with a comma separator, cardinal letters, and ASCII units.

```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;

?>
```

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

### Format Coordinate to GeoJSON Point

Source: https://phpgeo.marcusjaschen.de/600_Formatting_and_Output/100_Coordinates

Formats a coordinate object into a GeoJSON Point object. Note that the order of coordinates in GeoJSON is [longitude, latitude].

```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());

?>
```

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

### Calculate Perpendicular Distance

Source: https://phpgeo.marcusjaschen.de/400_Calculations/430_Perpendicular_Distance

Use the `PerpendicularDistance` class to find the shortest distance between a `Coordinate` object and a `Line` object. Ensure the `Location\*` and `Location\*` classes are imported.

```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)
);


```

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

### Calculate Final Bearing of a Line

Source: https://phpgeo.marcusjaschen.de/100_Geometries/120_Line

Calculates the final bearing of a line segment using the BearingEllipsoidal class. Requires Coordinate and Line instances.

```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);

?>
```
Tokens:
Raw