phpgeo 6.x

.github/workflows/ci.yml

@@ -16,9 +16,9 @@ jobs:
     strategy:
       matrix:
         php-versions:
-          - "8.1"
           - "8.2"
           - "8.3"
+          - "8.4"
 
     name: "phpgeo CI run - PHP ${{ matrix.php-versions }}"
 
@@ -54,7 +54,7 @@ jobs:
         run: composer run-script ci:sniff
 
       - name: Static Analysis
-        run: composer run-script ci:psalm
+        run: composer run-script ci:phpstan
 
       - name: Unit Tests
         run: composer run-script ci:tests

CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to `mjaschen/phpgeo` will be documented in this file.
 Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
 
+## [6.0.0]
+
+**Warning: Backwards-compatibility-breaking changes** (see README for upgrade details)
+
+### Added
+
+- Support for PHP 8.4
+- `GeometryLinesInterface` for geometries containing lines (`Line`, `Polyline`, `Polygon`)
+- `getBounds()` method to `GeometryInterface`
+
+### Removed
+
+- Support for PHP 8.1
+
+### Changed
+
+- Replaced Psalm with PHPStan for static code analysis
+
 ## [5.0.0]
 
 **Warning: Backwards-compatibility-breaking changes**

README.md

@@ -1,6 +1,7 @@
 # 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.
+phpgeo provides abstractions to geographical coordinates (including support for different ellipsoids) and allows you to
+calculate geographical distances between coordinates with high precision.
 
 [![Latest Stable Version](https://poser.pugx.org/mjaschen/phpgeo/v)](//packagist.org/packages/mjaschen/phpgeo)
 [![Total Downloads](https://poser.pugx.org/mjaschen/phpgeo/downloads)](//packagist.org/packages/mjaschen/phpgeo)
@@ -11,27 +12,28 @@ phpgeo provides abstractions to geographical coordinates (including support for
 
 ## Requirements
 
-Minimum required PHP version is 8.1. *phpgeo* is tested up to PHP 8.3.
+Minimum required PHP version is 8.2. *phpgeo* is tested up to PHP 8.4.
 
 New features will only go into the main branch and won't be backported.
 
 It's possible to install older versions of *phpgeo* for older PHP versions.
 Please refer to the following table for the compatibility matrix:
 
-| PHP Version | phpgeo Version |   Support Status   | Composer Install                        |
-| :---------: | :------------: | :----------------: | --------------------------------------- |
-|     8.3     |      5.x       |     ✅ active      | `composer require mjaschen/phpgeo`      |
-|     8.2     |      5.x       |     ✅ active      | `composer require mjaschen/phpgeo`      |
-|     8.1     |      5.x       |     ✅ active      | `composer require mjaschen/phpgeo`      |
+| 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` |
+|     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
 
@@ -51,15 +53,27 @@ Update the version constraint in the project's `composer.json` and
 run `composer update` or require the new version by running:
 
 ```shell
-composer require mjaschen/phpgeo:^5.0
+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.
+
+| 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.
+*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.
 
 | 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.                            |
 
@@ -69,27 +83,35 @@ Starting with version 2.0.0 phpgeo is licensed under the MIT license. Older vers
 
 ## Features
 
-**Info:** Please visit the **[documentation site](https://phpgeo.marcusjaschen.de/)** for complete and up-to-date documentation with many examples!
+**Info:** Please visit the **[documentation site](https://phpgeo.marcusjaschen.de/)** for complete and up-to-date
+documentation with many examples!
 
 phpgeo provides the following features (follow the links for examples):
 
-- abstractions of several geometry objects ([coordinate/point](https://phpgeo.marcusjaschen.de/Geometries/Coordinate.html),
+- abstractions of several geometry
+  objects ([coordinate/point](https://phpgeo.marcusjaschen.de/Geometries/Coordinate.html),
   [line](https://phpgeo.marcusjaschen.de/Geometries/Line.html),
   [polyline/GPS track](https://phpgeo.marcusjaschen.de/Geometries/Polyline.html),
   [polygon](https://phpgeo.marcusjaschen.de/Geometries/Polygon.html)
 - support for different [ellipsoids](https://phpgeo.marcusjaschen.de/Geometries/Ellipsoid.html), e.g. WGS-84
 - [length/distance/perimeter calculations](https://phpgeo.marcusjaschen.de/Calculations/Distance_and_Length.html)
   with different implementations (Haversine, Vincenty)
 - [Geofence](https://phpgeo.marcusjaschen.de/Calculations/Geofence.html) calculation,
-  i.e. answering the question "Is this point contained in that area/polygon?" and other [intersection](https://phpgeo.marcusjaschen.de/Comparisons/Intersections.html) checks between different geometries
+  i.e. answering the question "Is this point contained in that area/polygon?" and
+  other [intersection](https://phpgeo.marcusjaschen.de/Comparisons/Intersections.html) checks between different
+  geometries
 - [formatting and output](https://phpgeo.marcusjaschen.de/Formatting_and_Output/index.html) of geometry objects
   (GeoJSON, nice strings, e. g. `18° 54′ 41″ -155° 40′ 42″`)
-- calculation of [bearing angle between two points](https://phpgeo.marcusjaschen.de/Calculations/Bearing_and_Destination.html#page_Bearing-between-two-points)
+- calculation
+  of [bearing angle between two points](https://phpgeo.marcusjaschen.de/Calculations/Bearing_and_Destination.html#page_Bearing-between-two-points)
   (spherical or with Vincenty's formula)
-- calculation of a [destination point for a given starting point](https://phpgeo.marcusjaschen.de/Calculations/Bearing_and_Destination.html#page_Destination-point-for-given-bearing-and-distance),
+- calculation of
+  a [destination point for a given starting point](https://phpgeo.marcusjaschen.de/Calculations/Bearing_and_Destination.html#page_Destination-point-for-given-bearing-and-distance),
   bearing angle, and distance (spherical or with Vincenty's formula)
-- calculation of the [perpendicular distance between a point and a line](https://phpgeo.marcusjaschen.de/Calculations/Perpendicular_Distance.html)
-- calculation of the [Cardinal Distances between two points](https://phpgeo.marcusjaschen.de/Calculations/Cardinal_Distance.html)
+- calculation of
+  the [perpendicular distance between a point and a line](https://phpgeo.marcusjaschen.de/Calculations/Perpendicular_Distance.html)
+- calculation of
+  the [Cardinal Distances between two points](https://phpgeo.marcusjaschen.de/Calculations/Cardinal_Distance.html)
 - getting segments of a [polyline](https://phpgeo.marcusjaschen.de/Geometries/Polyline.html#page_Segments)
   /[polygon](https://phpgeo.marcusjaschen.de/Geometries/Polygon.html#page_Segments),
 - [reversing direction](https://phpgeo.marcusjaschen.de/Geometries/Polygon.html#page_Reverse-Direction)
@@ -134,7 +156,9 @@ echo $coordinate1->getDistance($coordinate2, new Vincenty()); // returns 128130.
 
 ### Simplifying a polyline
 
-Polylines can be simplified to save storage space or bandwidth. Simplification is done with the [Ramer–Douglas–Peucker algorithm](https://en.wikipedia.org/wiki/Ramer–Douglas–Peucker_algorithm) (AKA Douglas-Peucker algorithm).
+Polylines can be simplified to save storage space or bandwidth. Simplification is done with
+the [Ramer–Douglas–Peucker algorithm](https://en.wikipedia.org/wiki/Ramer–Douglas–Peucker_algorithm) (AKA
+Douglas-Peucker algorithm).
 
 ```php
 <?php
@@ -164,7 +188,8 @@ $simplified = $processor->simplify(1500000);
 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.
 
-**Warning:** The calculation gives wrong results if the polygons has points on both sides of the 180/-180 degrees meridian.
+**Warning:** The calculation gives wrong results if the polygons has points on both sides of the 180/-180 degrees
+meridian.
 
 ```php
 <?php
@@ -255,10 +280,10 @@ Of course, it's possible to use the test runners directly, e.g. for PHPUnit:
 ./vendor/bin/phpunit
 ```
 
-Psalm:
+PHPStan:
 
 ```shell
-./vendor/bin/psalm
+./vendor/bin/phpstan
 ```
 
 ### Running GitHub Actions locally
@@ -272,8 +297,11 @@ act --rm -P ubuntu-latest=shivammathur/node:latest
 ## Credits
 
 * Marcus Jaschen <[email protected]> and [all contributors](https://github.com/mjaschen/phpgeo/graphs/contributors)
-* [Chris Veness](http://www.movable-type.co.uk/scripts/latlong-vincenty.html) - JavaScript implementation of the [Vincenty formula](http://en.wikipedia.org/wiki/Vincenty%27s_formulae) for distance calculation
-* Ersts,P.J., Horning, N., and M. Polin[Internet] Perpendicular Distance Calculator(version 1.2.2) [Documentation](http://biodiversityinformatics.amnh.org/open_source/pdc/documentation.php). 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](http://www.ecse.rpi.edu/Homepages/wrf/Research/Short_Notes/pnpoly.html)
-
-[Psalm]: https://github.com/vimeo/psalm
+* [Chris Veness](http://www.movable-type.co.uk/scripts/latlong-vincenty.html) - JavaScript implementation of
+  the [Vincenty formula](http://en.wikipedia.org/wiki/Vincenty%27s_formulae) for distance calculation
+* Ersts,P.J., Horning, N., and M. Polin[Internet] Perpendicular Distance Calculator(version
+  1.2.2) [Documentation](http://biodiversityinformatics.amnh.org/open_source/pdc/documentation.php). 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](http://www.ecse.rpi.edu/Homepages/wrf/Research/Short_Notes/pnpoly.html)

composer.json

@@ -42,28 +42,28 @@
         "email" : "[email protected]"
     },
     "require": {
-        "php": "^8.1"
+        "php": "^8.2"
     },
     "autoload": {
         "psr-4": {
             "Location\\": "src/"
         }
     },
     "require-dev": {
-        "phpunit/phpunit": "^10.0",
-        "vimeo/psalm": "^5.0",
+        "phpunit/phpunit": "^11.0",
+        "phpstan/phpstan": "^2.0",
         "squizlabs/php_codesniffer": "^3.7"
     },
     "scripts": {
         "ci:composer-validate": "composer validate --no-check-all --no-check-lock --strict",
         "ci:lint": "find src tests -name '*.php' -print0 | xargs -0 -n 1 -P 4 php -l",
-        "ci:psalm": "./vendor/bin/psalm",
+        "ci:phpstan": "./vendor/bin/phpstan",
         "ci:sniff": "./vendor/bin/phpcs src tests",
         "ci:tests": "./vendor/bin/phpunit tests/",
         "ci:static": [
             "@ci:composer-validate",
             "@ci:lint",
-            "@ci:psalm",
+            "@ci:phpstan",
             "@ci:sniff"
         ],
         "ci:dynamic": [

phpstan.neon

@@ -0,0 +1,6 @@
+
+parameters:
+    editorUrl: 'phpstorm://open?file=%%file%%&line=%%line%%'
+    level: 7
+    paths:
+        - src

src/Bearing/BearingEllipsoidal.php

@@ -180,7 +180,7 @@ private function inverseVincenty(Coordinate $point1, Coordinate $point2): Invers
             $sinσ = sqrt($sinSqσ);
 
             if ($sinσ == 0) {
-                new InverseVincentyBearing(0, 0, 0);
+                return new InverseVincentyBearing(0, 0, 0);
             }
 
             $cosσ = $sinU1 * $sinU2 + $cosU1 * $cosU2 * $cosλ;

src/CardinalDirection/CardinalDirectionDistances.php

@@ -6,7 +6,6 @@
 
 use Location\Exception\InvalidDistanceException;
 
-/** @psalm-immutable */
 class CardinalDirectionDistances
 {
     private function __construct(
@@ -17,18 +16,11 @@ private function __construct(
     ) {
     }
 
-    /**
-     * @psalm-pure
-     * @psalm-mutation-free
-     */
     public static function create(): self
     {
         return new self(0, 0, 0, 0);
     }
 
-    /**
-     * @psalm-mutation-free
-     */
     public function setNorth(float $north): self
     {
         $this->assertPositiveFloat($north);
@@ -37,9 +29,6 @@ public function setNorth(float $north): self
     }
 
     /**
-     * @psalm-pure
-     * @psalm-mutation-free
-     *
      * @throws InvalidDistanceException
      */
     private function assertPositiveFloat(float $value): void
@@ -49,63 +38,42 @@ private function assertPositiveFloat(float $value): void
         }
     }
 
-    /**
-     * @psalm-mutation-free
-     */
     public function setEast(float $east): self
     {
         $this->assertPositiveFloat($east);
 
         return new self($this->north, $east, $this->south, $this->west);
     }
 
-    /**
-     * @psalm-mutation-free
-     */
     public function setSouth(float $south): self
     {
         $this->assertPositiveFloat($south);
 
         return new self($this->north, $this->east, $south, $this->west);
     }
 
-    /**
-     * @psalm-mutation-free
-     */
     public function setWest(float $west): self
     {
         $this->assertPositiveFloat($west);
 
         return new self($this->north, $this->east, $this->south, $west);
     }
 
-    /**
-     * @psalm-mutation-free
-     */
     public function getNorth(): float
     {
         return $this->north;
     }
 
-    /**
-     * @psalm-mutation-free
-     */
     public function getEast(): float
     {
         return $this->east;
     }
 
-    /**
-     * @psalm-mutation-free
-     */
     public function getSouth(): float
     {
         return $this->south;
     }
 
-    /**
-     * @psalm-mutation-free
-     */
     public function getWest(): float
     {
         return $this->west;