update README + change log

mjaschen · Jan 12, 2025 · 3c375fa · 3c375fa
1 parent 0e3ad18
commit 3c375fa
Show file tree

Hide file tree

Showing 2 changed files with 73 additions and 33 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,11 +3,23 @@
 All notable changes to `mjaschen/phpgeo` will be documented in this file.
 Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
 
-## [5.1.0]
+## [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]
 

diff --git a/README.md b/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 <mail@marcusjaschen.de> 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)