From 3c375fafcbb9b23103dcc3a253499cb38b3c4be2 Mon Sep 17 00:00:00 2001 From: Marcus Jaschen Date: Sun, 12 Jan 2025 09:58:06 +0100 Subject: [PATCH] update README + change log --- CHANGELOG.md | 14 +++++++- README.md | 92 ++++++++++++++++++++++++++++++++++------------------ 2 files changed, 73 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 963efd2..bab2a27 100644 --- 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 index 7d20ba0..2f19326 100644 --- 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,11 +83,13 @@ 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) @@ -81,15 +97,21 @@ phpgeo provides the following features (follow the links for examples): - [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 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 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)