Merge branch 'geometry_service' into v0.8

CHANGELOG.md

@@ -2,11 +2,90 @@
 
 ## UNRELEASED (0.8.0)
 
-💥 **Breaking change**
+💥 **Breaking changes**
+
+**Minimum PHP version is now `8.0`.**
+
+The global `GeometryEngineRegistry` is gone. All convenience methods that rely on the `GeometryEngine` are deprecated, and need the `GeometryEngine` to be passed explicitly as an extra argument.
+You should now explicitly call the `GeometryEngine`, that you can get injected with your dependency injection container.
+
+For example, the following call:
+
+```php
+$lineString->length();
+```
 
-- Minimum PHP version is now 8.0
+Should be replaced with:
+
+```php
+$geometryEngine->length($lineString);
+```
+
+You can still call it this way for now:
+
+```php
+$lineString->length($geometryEngine);
+```
 
-💥 **Non-breaking change**
+But this behaviour is deprecated and will be removed in a future version.
+
+**Detail of breaking changes**
+
+The following class has been removed:
+
+- `GeometryEngineRegistry`
+
+The following method has been added:
+
+- `GeometryEngine::isRing()`
+
+The following method signatures have been changed:
+
+- `GeometryEngine::boundingPolygons()`
+
+The following methods have been deprecated, and now need an extra `GeometryEngine` parameter:
+
+- `Curve::isClosed()`
+- `Curve::isRing()`
+- `Curve::length()`
+- `Geometry::boundary()`
+- `Geometry::buffer()`
+- `Geometry::centroid()`
+- `Geometry::contains()`
+- `Geometry::convexHull()`
+- `Geometry::crosses()`
+- `Geometry::difference()`
+- `Geometry::disjoint()`
+- `Geometry::distance()`
+- `Geometry::equals()`
+- `Geometry::envelope()`
+- `Geometry::intersection()`
+- `Geometry::intersects()`
+- `Geometry::isSimple()`
+- `Geometry::isValid()`
+- `Geometry::locateAlong()`
+- `Geometry::locateBetween()`
+- `Geometry::maxDistance()`
+- `Geometry::overlaps()`
+- `Geometry::relate()`
+- `Geometry::simplify()`
+- `Geometry::snapToGrid()`
+- `Geometry::symDifference()`
+- `Geometry::touches()`
+- `Geometry::transform()`
+- `Geometry::union()`
+- `Geometry::within()`
+- `MultiCurve::isClosed()`
+- `MultiCurve::length()`
+- `MultiSurface::area()`
+- `MultiSurface::pointOnSurface()`
+- `Point::azimuth()`
+- `PolyhedralSurface::boundingPolygons()`
+- `PolyhedralSurface::isClosed()`
+- `Surface::area()`
+- `Surface::pointOnSurface()`
+
+- 💥 **Non-breaking changes**
 
 - The following signatures have changed, but are not a breaking change due to LSP:
   - `DatabaseEngine::getParameterPlaceholder(mixed $parameter): string`

README.md

@@ -77,11 +77,10 @@ Following is a step-by-step guide for all possible configurations:
 - Use this bootstrap code in your project:
 
     ```php
-    use Brick\Geo\Engine\GeometryEngineRegistry;
     use Brick\Geo\Engine\PDOEngine;
 
     $pdo = new PDO('mysql:host=localhost', 'root', '');
-    GeometryEngineRegistry::set(new PDOEngine($pdo));
+    $geometryEngine = new PDOEngine($pdo);
     ```
 
 Update the code with your own connection parameters, or use an existing `PDO` connection if you have one (recommended).
@@ -109,11 +108,10 @@ Just ensure that your MariaDB version is `5.5` or greater.
 - Use this bootstrap code in your project:
 
     ```php
-    use Brick\Geo\Engine\GeometryEngineRegistry;
     use Brick\Geo\Engine\PDOEngine;
 
     $pdo = new PDO('pgsql:host=localhost', 'postgres', '');
-    GeometryEngineRegistry::set(new PDOEngine($pdo));
+    $geometryEngine = new PDOEngine($pdo);
     ```
 
 Update the code with your own connection parameters, or use an existing `PDO` connection if you have one (recommended).
@@ -149,12 +147,11 @@ all you need to do is create an additional in-memory SQLite3 database just to po
 - Use this bootstrap code in your project:
 
     ```php
-    use Brick\Geo\Engine\GeometryEngineRegistry;
     use Brick\Geo\Engine\SQLite3Engine;
 
     $sqlite3 = new SQLite3(':memory:');
     $sqlite3->loadExtension('mod_spatialite.so');
-    GeometryEngineRegistry::set(new SQLite3Engine($sqlite3));
+    $geometryEngine = new SQLite3Engine($sqlite3);
     ```
 
 - Depending on the functions you use, you will probably need to initialize the spatial metadata by running this query:
@@ -181,10 +178,9 @@ In this example we have created an in-memory database for our GIS calculations,
 - Use this bootstrap code in your project:
 
     ```php
-    use Brick\Geo\Engine\GeometryEngineRegistry;
     use Brick\Geo\Engine\GEOSEngine;
 
-    GeometryEngineRegistry::set(new GEOSEngine());
+    $geometryEngine = new GEOSEngine();
     ```
 </details>
 
@@ -238,9 +234,9 @@ Example
 use Brick\Geo\Polygon;
 
 $polygon = Polygon::fromText('POLYGON ((0 0, 0 3, 3 3, 0 0))');
-echo $polygon->area(); // 4.5
+echo $geometryEngine->area($polygon); // 4.5
 
-$centroid = $polygon->centroid();
+$centroid = $geometryEngine->centroid($polygon);
 echo $centroid->asText(); // POINT (1 2)
 ```
 

phpunit-bootstrap.php

@@ -1,6 +1,5 @@
 <?php
 
-use Brick\Geo\Engine\GeometryEngineRegistry;
 use Brick\Geo\Engine\PDOEngine;
 use Brick\Geo\Engine\SQLite3Engine;
 use Brick\Geo\Engine\GEOSEngine;
@@ -95,6 +94,6 @@
                 exit(1);
         }
 
-        GeometryEngineRegistry::set($engine);
+        $GLOBALS['GEOMETRY_ENGINE'] = $engine;
     }
 })();

src/Curve.php

@@ -4,7 +4,7 @@
 
 namespace Brick\Geo;
 
-use Brick\Geo\Engine\GeometryEngineRegistry;
+use Brick\Geo\Engine\GeometryEngine;
 use Brick\Geo\Exception\EmptyGeometryException;
 use Brick\Geo\Exception\GeometryEngineException;
 
@@ -28,13 +28,15 @@ public function dimension() : int
     /**
      * Returns the length of this Curve in its associated spatial reference.
      *
+     * @deprecated Please use `$geometryEngine->length()`.
+     *
      * @noproxy
      *
      * @throws GeometryEngineException If the operation is not supported by the geometry engine.
      */
-    public function length() : float
+    public function length(GeometryEngine $geometryEngine) : float
     {
-        return GeometryEngineRegistry::get()->length($this);
+        return $geometryEngine->length($this);
     }
 
     /**
@@ -56,13 +58,15 @@ abstract public function endPoint() : Point;
      *
      * The curve is closed if `startPoint()` == `endPoint()`.
      *
+     * @deprecated Please use `$geometryEngine->isClosed()`.
+     *
      * @noproxy
      *
      * @throws GeometryEngineException If the operation is not supported by the geometry engine.
      */
-    public function isClosed() : bool
+    public function isClosed(GeometryEngine $geometryEngine) : bool
     {
-        return GeometryEngineRegistry::get()->isClosed($this);
+        return $geometryEngine->isClosed($this);
     }
 
     /**
@@ -73,12 +77,14 @@ public function isClosed() : bool
      * The curve is closed if its start point is equal to its end point.
      * The curve is simple if it does not pass through the same point more than once.
      *
+     * @deprecated Please use `$geometryEngine->isRing()`.
+     *
      * @noproxy
      *
      * @throws GeometryEngineException If the operation is not supported by the geometry engine.
      */
-    public function isRing() : bool
+    public function isRing(GeometryEngine $geometryEngine) : bool
     {
-        return $this->isClosed() && $this->isSimple();
+        return $geometryEngine->isRing($this);
     }
 }

src/Engine/DatabaseEngine.php

@@ -9,7 +9,9 @@
 use Brick\Geo\Geometry;
 use Brick\Geo\MultiCurve;
 use Brick\Geo\MultiSurface;
+use Brick\Geo\MultiPolygon;
 use Brick\Geo\Point;
+use Brick\Geo\Polygon;
 use Brick\Geo\Proxy;
 use Brick\Geo\Surface;
 
@@ -335,6 +337,16 @@ public function isSimple(Geometry $g) : bool
         return $this->queryBoolean('ST_IsSimple', $g);
     }
 
+    public function isRing(Curve $curve) : bool
+    {
+        try {
+            return $this->queryBoolean('ST_IsRing', $curve);
+        } catch (GeometryEngineException $e) {
+            // Not all RDBMS (hello, MySQL) support ST_IsRing(), but we have an easy fallback
+            return $this->isClosed($curve) && $this->isSimple($curve);
+        }
+    }
+
     public function equals(Geometry $a, Geometry $b) : bool
     {
         return $this->queryBoolean('ST_Equals', $a, $b);
@@ -415,7 +427,7 @@ public function maxDistance(Geometry $a, Geometry $b) : float
         return $this->queryFloat('ST_MaxDistance', $a, $b);
     }
 
-    public function boundingPolygons(Geometry $g) : Geometry
+    public function boundingPolygons(Polygon $p) : MultiPolygon
     {
         throw GeometryEngineException::unimplementedMethod(__METHOD__);
     }

src/Engine/GEOSEngine.php

@@ -13,6 +13,8 @@
 use Brick\Geo\MultiSurface;
 use Brick\Geo\Point;
 use Brick\Geo\Surface;
+use Brick\Geo\MultiPolygon;
+use Brick\Geo\Polygon;
 use GEOSWKBReader;
 use GEOSWKBWriter;
 use GEOSWKTReader;
@@ -192,6 +194,15 @@ public function isSimple(Geometry $g) : bool
         }
     }
 
+    public function isRing(Curve $curve) : bool
+    {
+        try {
+            return $this->toGEOS($curve)->isRing();
+        } catch (\Exception $e) {
+            throw GeometryEngineException::operationNotSupportedByEngine($e);
+        }
+    }
+
     public function equals(Geometry $a, Geometry $b) : bool
     {
         try {
@@ -352,7 +363,7 @@ public function maxDistance(Geometry $a, Geometry $b) : float
         throw GeometryEngineException::unimplementedMethod(__METHOD__);
     }
 
-    public function boundingPolygons(Geometry $g) : Geometry
+    public function boundingPolygons(Polygon $p) : MultiPolygon
     {
         throw GeometryEngineException::unimplementedMethod(__METHOD__);
     }