feat(#305): add support for PostGIS's types of GEOGRAPHY, GEOMETRY and their array variations

.github/workflows/integration-tests.yml

@@ -34,17 +34,18 @@ jobs:
     needs: should-run
     if: needs.should-run.outputs.run == 'true'
     runs-on: ubuntu-latest
-    name: "PostgreSQL ${{ matrix.postgres }} + PHP ${{ matrix.php }}"
+    name: "PostgreSQL ${{ matrix.postgres }} + PostGIS ${{ matrix.postgis }} + PHP ${{ matrix.php }}"
 
     strategy:
       fail-fast: false
       matrix:
         php: ['8.1', '8.2', '8.3', '8.4']
         postgres: ['16', '17']
+        postgis: ['3.4', '3.5']
 
     services:
       postgres:
-        image: postgres:${{ matrix.postgres }}
+        image: postgis/postgis:${{ matrix.postgres }}-${{ matrix.postgis }}
         env:
           POSTGRES_PASSWORD: postgres
           POSTGRES_USER: postgres
@@ -106,6 +107,9 @@ jobs:
           echo "\nListing available PostgreSQL extensions:"
           PGPASSWORD=postgres psql -h localhost -U postgres -d postgres_doctrine_test -c "SELECT * FROM pg_available_extensions;"
 
+          echo "\nVerifying PostGIS installation:"
+          PGPASSWORD=postgres psql -h localhost -U postgres -d postgres_doctrine_test -c "SELECT PostGIS_Version();"
+
       - name: Run integration test suite
         run: composer run-integration-tests
         env:

README.md

@@ -55,6 +55,8 @@ This package provides comprehensive Doctrine support for PostgreSQL features:
   - MAC addresses (`macaddr`, `macaddr[]`)
 - **Geometric Types**
   - Point (`point`, `point[]`)
+  - PostGIS Geometry (`geometry`)
+  - PostGIS Geography (`geography`)
 - **Range Types**
   - Date and time ranges (`daterange`, `tsrange`, `tstzrange`)
   - Numeric ranges (`numrange`, `int4range`, `int8range`)
@@ -122,10 +124,10 @@ composer run-unit-tests
 ```
 
 ### PostgreSQL Integration Tests
-We also provide integration tests that run against a real PostgreSQL database to ensure compatibility:
+We also provide integration tests that run against a real PostgreSQL database with PostGIS to ensure compatibility:
 
 ```bash
-# Start PostgreSQL using Docker Compose
+# Start PostgreSQL with PostGIS using Docker Compose
 docker-compose up -d
 
 # Run integration tests
@@ -135,7 +137,7 @@ composer run-integration-tests
 docker-compose down -v
 ```
 
-See [tests-integration/README.md](tests-integration/README.md) for more details.
+See [tests/Integration/README.md](tests/Integration/README.md) for more details.
 
 ## ⭐ Support the Project
 

devenv.nix

@@ -60,14 +60,26 @@ in
   services.postgres = {
     enable = true;
 
+    # Use PostgreSQL 17 to match Docker Compose and CI
+    package = pkgs.postgresql_17;
+
     listen_addresses = "127.0.0.1";
     port = config.env.POSTGRES_PORT;
 
     initialDatabases = [ { name = config.env.POSTGRES_DB; } ];
 
+    # Enable PostGIS extension
+    extensions = extensions: [
+      extensions.postgis
+    ];
+
     initialScript = ''
       CREATE ROLE "${config.env.POSTGRES_USER}"
         WITH SUPERUSER LOGIN PASSWORD '${config.env.POSTGRES_PASSWORD}';
+
+      -- Enable PostGIS extension in the database
+      \c ${config.env.POSTGRES_DB}
+      CREATE EXTENSION IF NOT EXISTS postgis;
     '';
   };
 

docker-compose.yml

@@ -1,10 +1,11 @@
 services:
   postgres:
-    image: postgres:${POSTGRES_VERSION:-17}
+    image: postgis/postgis:${POSTGRES_VERSION:-17}-3.4
     environment:
       POSTGRES_USER: ${POSTGRES_USER:-postgres}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
       POSTGRES_DB: ${POSTGRES_DB:-postgres_doctrine_test}
+      TZ: UTC
     ports:
       - "${POSTGRES_PORT:-5432}:5432"
     volumes:

docs/AVAILABLE-TYPES.md

@@ -8,20 +8,28 @@
 | bigint[] | _int8 | `MartinGeorgiev\Doctrine\DBAL\Types\BigIntArray` |
 | real[] | _float4 | `MartinGeorgiev\Doctrine\DBAL\Types\RealArray` |
 | double precision[] | _float8 | `MartinGeorgiev\Doctrine\DBAL\Types\DoublePrecisionArray` |
-| text[] | _text | `MartinGeorgiev\Doctrine\DBAL\Types\TextArray` |
-| jsonb[] | _jsonb | `MartinGeorgiev\Doctrine\DBAL\Types\JsonbArray` |
+|---|---|---|
 | jsonb | jsonb | `MartinGeorgiev\Doctrine\DBAL\Types\Jsonb` |
-| inet | inet | `MartinGeorgiev\Doctrine\DBAL\Types\Inet` |
-| inet[] | _inet | `MartinGeorgiev\Doctrine\DBAL\Types\InetArray` |
+| jsonb[] | _jsonb | `MartinGeorgiev\Doctrine\DBAL\Types\JsonbArray` |
+| text[] | _text | `MartinGeorgiev\Doctrine\DBAL\Types\TextArray` |
+|---|---|---|
 | cidr | cidr | `MartinGeorgiev\Doctrine\DBAL\Types\Cidr` |
 | cidr[] | _cidr | `MartinGeorgiev\Doctrine\DBAL\Types\CidrArray` |
+| inet | inet | `MartinGeorgiev\Doctrine\DBAL\Types\Inet` |
+| inet[] | _inet | `MartinGeorgiev\Doctrine\DBAL\Types\InetArray` |
 | macaddr | macaddr | `MartinGeorgiev\Doctrine\DBAL\Types\Macaddr` |
 | macaddr[] | _macaddr | `MartinGeorgiev\Doctrine\DBAL\Types\MacaddrArray` |
-| point | point | `MartinGeorgiev\Doctrine\DBAL\Types\Point` |
-| point[] | _point | `MartinGeorgiev\Doctrine\DBAL\Types\PointArray` |
+|---|---|---|
 | daterange | daterange | `MartinGeorgiev\Doctrine\DBAL\Types\DateRange` |
 | int4range | int4range | `MartinGeorgiev\Doctrine\DBAL\Types\Int4Range` |
 | int8range | int8range | `MartinGeorgiev\Doctrine\DBAL\Types\Int8Range` |
 | numrange | numrange | `MartinGeorgiev\Doctrine\DBAL\Types\NumRange` |
 | tsrange | tsrange | `MartinGeorgiev\Doctrine\DBAL\Types\TsRange` |
 | tstzrange | tstzrange | `MartinGeorgiev\Doctrine\DBAL\Types\TstzRange` |
+|---|---|---|
+| geography | geography | `MartinGeorgiev\Doctrine\DBAL\Types\Geography` |
+| geography[] | _geography | `MartinGeorgiev\Doctrine\DBAL\Types\GeographyArray` |
+| geometry | geometry | `MartinGeorgiev\Doctrine\DBAL\Types\Geometry` |
+| geometry[] | _geometry | `MartinGeorgiev\Doctrine\DBAL\Types\GeometryArray` |
+| point | point | `MartinGeorgiev\Doctrine\DBAL\Types\Point` |
+| point[] | _point | `MartinGeorgiev\Doctrine\DBAL\Types\PointArray` |

docs/CONTRIBUTING.md

@@ -117,7 +117,7 @@ The provided environment includes:
 
 - PHP 8.1, which is the oldest PHP version supported by this project.
 - Composer
-- PostgreSQL 17, started by `devenv up`.
+- PostgreSQL 17 with PostGIS 3.4, started by `devenv up`.
 - Pre-commit hooks (PHP-CS-Fixer, PHPStan, Rector, deptrac, ...).
 
 ### Local development

docs/USE-CASES-AND-EXAMPLES.md

@@ -139,3 +139,32 @@ SELECT p FROM Product p WHERE CONTAINS(p.availabilityPeriod, DATERANGE('2024-06-
 -- Find products with prices in a specific range
 SELECT p FROM Product p WHERE p.priceRange @> 25.0
 ```
+
+
+Using PostGIS Types
+---
+
+The library provides DBAL type support for PostGIS `geometry` and `geography` columns. Example usage:
+
+```sql
+CREATE TABLE places (
+    id SERIAL PRIMARY KEY,
+    location GEOMETRY,
+    boundary GEOGRAPHY
+);
+```
+
+```php
+use Doctrine\DBAL\Types\Type;
+use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Geometry as GeometryValueObject;
+
+Type::addType('geography', MartinGeorgiev\Doctrine\DBAL\Types\Geography::class);
+Type::addType('geometry', MartinGeorgiev\Doctrine\DBAL\Types\Geometry::class);
+
+$location = GeometryValueObject::fromWKT('SRID=4326;POINT(-122.4194 37.7749)');
+$entity->setLocation($location);
+```
+
+Notes:
+- Values round-trip as EWKT/WKT strings at the database boundary.
+- Integration tests automatically enable the `postgis` extension; ensure PostGIS is available in your environment.

src/MartinGeorgiev/Doctrine/DBAL/Types/Point.php

@@ -7,6 +7,7 @@
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use MartinGeorgiev\Doctrine\DBAL\Types\Exceptions\InvalidPointForDatabaseException;
 use MartinGeorgiev\Doctrine\DBAL\Types\Exceptions\InvalidPointForPHPException;
+use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Exceptions\InvalidPointException;
 use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Point as PointValueObject;
 
 /**
@@ -46,7 +47,7 @@ public function convertToPHPValue($value, AbstractPlatform $platform): ?PointVal
 
         try {
             return PointValueObject::fromString($value);
-        } catch (\InvalidArgumentException) {
+        } catch (InvalidPointException) {
             throw InvalidPointForDatabaseException::forInvalidFormat($value);
         }
     }

src/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/Exceptions/InvalidGeometryException.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Exceptions;
+
+use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\WktGeometryType;
+
+/**
+ * Exception thrown when creating or manipulating Geometry value objects with invalid data.
+ * 
+ * This exception is specifically for validation errors within the Geometry value object itself,
+ * separate from DBAL conversion exceptions.
+ *
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+final class InvalidGeometryException extends \InvalidArgumentException
+{
+    public static function forEmptyWkt(): self
+    {
+        return new self('Empty Wkt string provided');
+    }
+
+    public static function forMissingSemicolonInEwkt(): self
+    {
+        return new self('Invalid Ewkt: missing semicolon after Srid prefix');
+    }
+
+    public static function forInvalidSridValue(mixed $sridValue): self
+    {
+        return new self(\sprintf('Invalid Srid value in Ewkt: %s', \var_export($sridValue, true)));
+    }
+
+    public static function forInvalidWktFormat(string $wkt): self
+    {
+        return new self(\sprintf('Invalid Wkt format: %s', \var_export($wkt, true)));
+    }
+
+    public static function forEmptyCoordinateSection(): self
+    {
+        return new self('Invalid Wkt: empty coordinate/body section');
+    }
+
+    public static function forUnsupportedGeometryType(string $type): self
+    {
+        $supportedTypes = \array_map(fn(WktGeometryType $case) => $case->value, WktGeometryType::cases());
+
+        return new self(\sprintf(
+            'Unsupported Wkt geometry type: %s. Supported types: %s',
+            \var_export($type, true),
+            \implode(', ', $supportedTypes)
+        ));
+    }
+}

src/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/Exceptions/InvalidPointException.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Exceptions;
+
+/**
+ * Exception thrown when creating or manipulating Point value objects with invalid data.
+ * 
+ * This exception is specifically for validation errors within the Point value object itself,
+ * separate from DBAL conversion exceptions.
+ *
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+final class InvalidPointException extends \InvalidArgumentException
+{
+    public static function forInvalidPointFormat(string $pointString, string $expectedPattern): self
+    {
+        return new self(\sprintf(
+            'Invalid point format. Expected format matching %s, got: %s',
+            \var_export($expectedPattern, true),
+            \var_export($pointString, true)
+        ));
+    }
+
+    public static function forInvalidCoordinate(string $coordinateName, string $value): self
+    {
+        return new self(\sprintf(
+            'Invalid %s coordinate format: %s',
+            \var_export($coordinateName, true),
+            \var_export($value, true)
+        ));
+    }
+}

src/MartinGeorgiev/Doctrine/DBAL/Types/ValueObject/Geometry.php

@@ -0,0 +1,103 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types\ValueObject;
+
+use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Exceptions\InvalidGeometryException;
+
+/**
+ * Lightweight Geometry value object supporting Ewkt (with optional Srid prefix) and Wkt.
+ *
+ * Examples:
+ * - POINT(1 2)
+ * - SRID=4326;POINT(-122.4194 37.7749)
+ * - LINESTRING(0 0, 1 1)
+ * - POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))
+ *
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+final class Geometry implements \Stringable
+{
+    private ?int $srid;
+
+    private WktGeometryType $wktType;
+
+    private string $wktBody;
+
+    private function __construct(?int $srid, WktGeometryType $wktType, string $wktBody)
+    {
+        $this->srid = $srid;
+        $this->wktType = $wktType;
+        $this->wktBody = $wktBody;
+    }
+
+    public static function fromWkt(string $wkt): self
+    {
+        $wkt = trim($wkt);
+        if ($wkt === '') {
+            throw InvalidGeometryException::forEmptyWkt();
+        }
+
+        $srid = null;
+        $expectSrid = str_starts_with($wkt, 'SRID=');
+        if ($expectSrid) {
+            $sridSeparatorPosition = strpos($wkt, ';');
+            if ($sridSeparatorPosition === false) {
+                throw InvalidGeometryException::forMissingSemicolonInEwkt();
+            }
+            $sridRawValue = substr($wkt, 5, $sridSeparatorPosition - 5);
+            if ($sridRawValue === '' || !ctype_digit($sridRawValue)) {
+                throw InvalidGeometryException::forInvalidSridValue($sridRawValue);
+            }
+            $srid = (int) $sridRawValue;
+            $wkt = substr($wkt, $sridSeparatorPosition + 1);
+        }
+
+        $wktTypeWithOptionalModifiersPattern = '/^([A-Z][A-Z0-9_]*)(?:\s+(?:ZM|Z|M))?\s*\((.*)\)$/s';
+        if (!preg_match($wktTypeWithOptionalModifiersPattern, $wkt, $matches)) {
+            throw InvalidGeometryException::forInvalidWktFormat($wkt);
+        }
+
+        $typeString = $matches[1];
+        $body = $matches[2];
+        if ($body === '') {
+            throw InvalidGeometryException::forEmptyCoordinateSection();
+        }
+
+        $geometryType = WktGeometryType::tryFrom($typeString);
+        if ($geometryType === null) {
+            throw InvalidGeometryException::forUnsupportedGeometryType($typeString);
+        }
+
+        return new self($srid, $geometryType, $body);
+    }
+
+    public function __toString(): string
+    {
+        $typeAndBody = $this->wktType->value.'('.$this->wktBody.')';
+        if ($this->srid === null) {
+            return $typeAndBody;
+        }
+
+        return 'SRID='.$this->srid.';'.$typeAndBody;
+    }
+
+    public function getSrid(): ?int
+    {
+        return $this->srid;
+    }
+
+    public function getGeometryType(): WktGeometryType
+    {
+        return $this->wktType;
+    }
+
+    public function getWkt(): string
+    {
+        return (string) $this;
+    }
+}
+