Dev/5.x (#105)

* update Composer dependencies (PHP 8.1+, PHPUnit 10, Psalm 5)
* make PHPUnit data provider methods static
* remove obsolete doc blocks
* use constructor property promotion
* deprecate getter methods
* mark constants as final
* use arrow functions
* code style
* throw JsonException when encoding fails
* use typed properties
* update return types
* use public properties instead of deprecated getters
* update Psalm config
* update README + change log
* update docs
* update GitHub Actions version matrix
* update change log

.github/workflows/ci.yml

@@ -16,11 +16,9 @@ jobs:
     strategy:
       matrix:
         php-versions:
-          - "7.3"
-          - "7.4"
-          - "8.0"
           - "8.1"
           - "8.2"
+          - "8.3"
 
     name: "phpgeo CI run - PHP ${{ matrix.php-versions }}"
 

CHANGELOG.md

@@ -3,23 +3,32 @@
 All notable changes to `mjaschen/phpgeo` will be documented in this file.
 Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
 
-## Unreleased/Upcoming
+## [5.0.0]
 
-### Added
-
-- `GeometryInterface` provides two new methods: `getBounds()` and `getSegments()`
+**Warning: Backwards-compatibility-breaking changes**
 
 ### Removed
 
-- Support for PHP 7.3
-- `setPoint1()` and `setPoint2()` methods from `Line`
-- `setSeparator()`, `useCardinalLetters()` and `setUnits()` methods from `DMS`
+- Support for PHP 7.3, 7.4 and 8.0
+- deprecated methods `setPoint1()` and `setPoint2()` from `Line`
+
+### Changed
+
+- `master` is now renamed to `main`
+- `GeometryFactoryInterface::fromString()` now has `GeometryInterface` as return type
+
+### Deprecated
+
+- deprecated methods `getDestination()` and `getBearingFinal()` from `DirectVincentyBearing`
+- deprecated methods `getDistance()`, `getBearingInitial()` and `getBearingFinal()` from `InverseVincentyBearing`
+- deprecated methods `getX()`, `getY()` and `getZ()` from `Cartesian`
+- deprecated methods `getPoint1()` and `getPoint2()` from `Line`
 
 ## [4.2.1] - 2023-12-03
 
 ### Changed
 
-- use proper variable as index for array access 
+- use proper variable as index for array access
 
 ## [4.2.0] - 2022-07-25
 

README.md

@@ -47,9 +47,18 @@ 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:^4.0
+composer require mjaschen/phpgeo:^5.0
 ```
 
+### 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.
+
+| 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.                            |
+
 ## License
 
 Starting with version 2.0.0 phpgeo is licensed under the MIT license. Older versions were GPL-licensed.

composer.json

@@ -42,17 +42,17 @@
         "email" : "mjaschen@gmail.com"
     },
     "require": {
-        "php": "^7.3 || ^8.0"
+        "php": "^8.1"
     },
     "autoload": {
         "psr-4": {
             "Location\\": "src/"
         }
     },
     "require-dev": {
-        "phpunit/phpunit": "^9.5",
-        "vimeo/psalm": "^4.13",
-        "squizlabs/php_codesniffer": "^3.6"
+        "phpunit/phpunit": "^10.0",
+        "vimeo/psalm": "^5.0",
+        "squizlabs/php_codesniffer": "^3.7"
     },
     "scripts": {
         "ci:composer-validate": "composer validate --no-check-all --no-check-lock --strict",

docs/000_Introduction.md

@@ -1,15 +1,15 @@
 # What is *phpgeo?*
 
-_phpgeo_ is a small PHP library which provides abstractions to geographical
+*phpgeo* is a small PHP library which provides abstractions to geographical
 coordinates (including support for different ellipsoids), polylines
-("GPS Tracks"), polygons, bounds, and more. _phpgeo_ allows you to perform
+("GPS Tracks"), polygons, bounds, and more. *phpgeo* allows you to perform
 different calculations with these abstractions, as distances, track
 lengths, etc.
 
-_phpgeo_ is developed by [Marcus Jaschen](https://www.marcusjaschen.de/) and all
+*phpgeo* is developed by [Marcus Jaschen](https://www.marcusjaschen.de/) and all
 [contributors](https://github.com/mjaschen/phpgeo/graphs/contributors).
 
-_phpgeo_ is licensed under the [MIT License](https://opensource.org/licenses/MIT).
+*phpgeo* is licensed under the [MIT License](https://opensource.org/licenses/MIT).
 
 The project is hosted on GitHub:
 

docs/010_Installation.md

@@ -2,23 +2,25 @@
 
 ## Requirements
 
-_phpgeo_ requires at least PHP 7.3. _phpgeo_ fully supports PHP 8.
+*phpgeo* requires at least PHP 8.1.
 
-The 3.x releases require PHP >= 7.2 but don't get feature updates any longer. Bugfixes will be backported.
+The 4.x releases require PHP >= 7.3 but don't get feature updates any longer. Bugfixes will be backported.
+
+The 3.x releases require PHP >= 7.2 but don't get feature updates any longer. Bugfixes won't be backported.
 
 The 2.x releases require PHP >= 7.0 but don't get feature updates any longer. Bugfixes won't be backported.
 
 The 1.x release line has support for PHP >= 5.4. Bugfixes won't be backported.
 
 ## Installation
 
-_phpgeo_ is best be installed using Composer. Please visit the
+*phpgeo* is best be installed using Composer. Please visit the
 [Composer website](https://getcomposer.org/) for more information.
 
-To install _phpgeo,_ simply “require” it using Composer:
+To install *phpgeo,* simply “require” it using Composer:
 
 ``` shell
 composer require mjaschen/phpgeo
 ```
 
-_phpgeo_ is now ready to be used in your project!
+*phpgeo* is now ready to be used in your project!

docs/015_Upgrading.md

@@ -1,10 +1,27 @@
 # Upgrading phpgeo
 
+## Update from phpgeo 4.x to phpgeo 5.x
+
+### Requirements
+
+- *phpgeo* 5.x requires at least PHP 8.1.
+
+### Update phpgeo
+
+- run `composer require mjaschen/phpgeo:^5.0` or
+- update the version constraint in your `composer.json` to `^5.0` and run `composer update`
+
+### Update Your Code
+
+`setPoint1()` and `setPoint2()` methods were removed from `Line` – the `Line` class now is immutable. Use the constructor to create a new instance of `Line`.
+
+There are some new deprecations introduced in 5.0, please see the change log for a detailed list and update your code accordingly to be prepared for 6.0.
+
 ## Update from phpgeo 3.x to phpgeo 4.x
 
 ### Requirements
 
-- _phpgeo_ 4.x requires at least PHP 7.3 and fully supports PHP 8
+- *phpgeo* 4.x requires at least PHP 7.3 and fully supports PHP 8
 
 ### Update phpgeo
 
@@ -22,7 +39,7 @@ No breaking changes were introduced with *phpgeo* 3.0.
 
 ### Requirements
 
-- _phpgeo_ 3.x requires at least PHP 7.2
+- *phpgeo* 3.x requires at least PHP 7.2
 
 ### Update phpgeo
 

docs/020_Development.md

@@ -2,7 +2,7 @@
 
 ## Run Tests
 
-_phpgeo_ provides unit tests with a quite good coverage. For an easy usage,
+*phpgeo* provides unit tests with a quite good coverage. For an easy usage,
 the test command is wrapped as a Composer script:
 
 ``` shell
@@ -16,39 +16,12 @@ Of course, it's possible to run PHPUnit directly:
 ```
 
 To test against another PHP version you can use Docker. The following command runs
-the tests using PHP 7.3:
+the tests using PHP 8.3:
 
 ``` shell
 docker run -it --rm --name phpgeo-phpunit \
     -v "$PWD":/usr/src/phpgeo \
-    -w /usr/src/phpgeo php:7.3-cli \
-    php vendor/bin/phpunit
-```
-
-Or PHP 7.4:
-
-``` shell
-docker run -it --rm --name phpgeo-phpunit \
-    -v "$PWD":/usr/src/phpgeo \
-    -w /usr/src/phpgeo php:7.4-cli \
-    php vendor/bin/phpunit
-```
-
-PHP 8.0:
-
-``` shell
-docker run -it --rm --name phpgeo-phpunit \
-    -v "$PWD":/usr/src/phpgeo \
-    -w /usr/src/phpgeo php:8.0-cli \
-    php vendor/bin/phpunit
-```
-
-PHP 8.1:
-
-``` shell
-docker run -it --rm --name phpgeo-phpunit \
-    -v "$PWD":/usr/src/phpgeo \
-    -w /usr/src/phpgeo php:8.1-cli \
+    -w /usr/src/phpgeo php:8.3-cli \
     php vendor/bin/phpunit
 ```
 
@@ -74,7 +47,7 @@ composer ci
 … or run all CI tasks with different PHP versions one after another:
 
 ```shell
-for PHP_VERSION in 7.3 7.4 8.0 8.1 ; do \
+for PHP_VERSION in 8.1 8.2 8.3 ; do \
   docker run -it --rm -v "$PWD":/phpgeo -w /phpgeo \
   ghcr.io/mjaschen/php:${PHP_VERSION}-cli-mj composer ci || break ; \
 done

phpunit.xml

@@ -1,14 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="tests/bootstrap.php" colors="true" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
-  <coverage>
-    <include>
-      <directory>src</directory>
-    </include>
-  </coverage>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="tests/bootstrap.php" colors="true" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd">
+  <coverage/>
   <testsuites>
     <testsuite name="Location Test Suite">
       <directory>tests/Location/</directory>
       <directory>tests/Regression/</directory>
     </testsuite>
   </testsuites>
+  <source>
+    <include>
+      <directory>src</directory>
+    </include>
+  </source>
 </phpunit>

psalm.xml

@@ -1,6 +1,8 @@
 <?xml version="1.0"?>
 <psalm
     resolveFromConfigFile="true"
+    findUnusedBaselineEntry="true"
+    findUnusedCode="false"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"

src/Bearing/BearingEllipsoidal.php

@@ -16,8 +16,6 @@
  * has done. For more information visit the following URL.
  *
  * @see http://www.movable-type.co.uk/scripts/latlong-vincenty.html
- *
- * @author Marcus Jaschen <mjaschen@gmail.com>
  */
 class BearingEllipsoidal implements BearingInterface
 {
@@ -28,9 +26,6 @@ class BearingEllipsoidal implements BearingInterface
      * If the two points share the same location, the bearing
      * value will be 0.0.
      *
-     * @param Coordinate $point1
-     * @param Coordinate $point2
-     *
      * @return float Bearing Angle
      */
     public function calculateBearing(Coordinate $point1, Coordinate $point2): float
@@ -39,62 +34,46 @@ public function calculateBearing(Coordinate $point1, Coordinate $point2): float
             return 0.0;
         }
 
-        return $this->inverseVincenty($point1, $point2)->getBearingInitial();
+        return $this->inverseVincenty($point1, $point2)->bearingInitial;
     }
 
     /**
      * Calculates the final bearing between the two points.
      *
-     * @param Coordinate $point1
-     * @param Coordinate $point2
-     *
-     * @return float
+     * @return float Bearing Angle
      */
     public function calculateFinalBearing(Coordinate $point1, Coordinate $point2): float
     {
-        return $this->inverseVincenty($point1, $point2)->getBearingFinal();
+        return $this->inverseVincenty($point1, $point2)->bearingFinal;
     }
 
     /**
      * Calculates a destination point for the given point, bearing angle,
      * and distance.
      *
-     * @param Coordinate $point
      * @param float $bearing the bearing angle between 0 and 360 degrees
      * @param float $distance the distance to the destination point in meters
-     *
-     * @return Coordinate
      */
     public function calculateDestination(Coordinate $point, float $bearing, float $distance): Coordinate
     {
-        return $this->directVincenty($point, $bearing, $distance)->getDestination();
+        return $this->directVincenty($point, $bearing, $distance)->destination;
     }
 
     /**
      * Calculates the final bearing angle for a destination point.
      * The method expects a starting point point, the bearing angle,
      * and the distance to destination.
      *
-     * @param Coordinate $point
-     * @param float $bearing
-     * @param float $distance
-     *
-     * @return float
+     * @return float Bearing Angle
      *
      * @throws NotConvergingException
      */
     public function calculateDestinationFinalBearing(Coordinate $point, float $bearing, float $distance): float
     {
-        return $this->directVincenty($point, $bearing, $distance)->getBearingFinal();
+        return $this->directVincenty($point, $bearing, $distance)->bearingFinal;
     }
 
     /**
-     * @param Coordinate $point
-     * @param float $bearing
-     * @param float $distance
-     *
-     * @return DirectVincentyBearing
-     *
      * @throws NotConvergingException
      */
     private function directVincenty(Coordinate $point, float $bearing, float $distance): DirectVincentyBearing
@@ -167,11 +146,6 @@ private function directVincenty(Coordinate $point, float $bearing, float $distan
     }
 
     /**
-     * @param Coordinate $point1
-     * @param Coordinate $point2
-     *
-     * @return InverseVincentyBearing
-     *
      * @throws NotConvergingException
      */
     private function inverseVincenty(Coordinate $point1, Coordinate $point2): InverseVincentyBearing