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/Exceptions/InvalidGeographyForDatabaseException.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types\Exceptions;
+
+use Doctrine\DBAL\Types\ConversionException;
+
+/**
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+final class InvalidGeographyForDatabaseException extends ConversionException
+{
+    private static function create(string $message, mixed $value): self
+    {
+        return new self(\sprintf($message, \var_export($value, true)));
+    }
+
+    public static function forInvalidType(mixed $value): self
+    {
+        return self::create('Database value must be a string, %s given', $value);
+    }
+
+    public static function forInvalidFormat(mixed $value): self
+    {
+        return self::create('Invalid geography format in database: %s', $value);
+    }
+}

src/MartinGeorgiev/Doctrine/DBAL/Types/Exceptions/InvalidGeographyForPHPException.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types\Exceptions;
+
+use Doctrine\DBAL\Types\ConversionException;
+
+/**
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+final class InvalidGeographyForPHPException extends ConversionException
+{
+    private static function create(string $message, mixed $value): self
+    {
+        return new self(\sprintf($message, \var_export($value, true)));
+    }
+
+    public static function forInvalidType(mixed $value): self
+    {
+        return self::create('Value must be a Geography value object, %s given', $value);
+    }
+
+    public static function forInvalidFormat(mixed $value): self
+    {
+        return self::create('Invalid Geography value object format: %s', $value);
+    }
+}

src/MartinGeorgiev/Doctrine/DBAL/Types/Exceptions/InvalidGeometryForDatabaseException.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types\Exceptions;
+
+use Doctrine\DBAL\Types\ConversionException;
+
+/**
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+final class InvalidGeometryForDatabaseException extends ConversionException
+{
+    private static function create(string $message, mixed $value): self
+    {
+        return new self(\sprintf($message, \var_export($value, true)));
+    }
+
+    public static function forInvalidType(mixed $value): self
+    {
+        return self::create('Database value must be a string, %s given', $value);
+    }
+
+    public static function forInvalidFormat(mixed $value): self
+    {
+        return self::create('Invalid geometry format in database: %s', $value);
+    }
+}

src/MartinGeorgiev/Doctrine/DBAL/Types/Exceptions/InvalidGeometryForPHPException.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types\Exceptions;
+
+use Doctrine\DBAL\Types\ConversionException;
+
+/**
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+final class InvalidGeometryForPHPException extends ConversionException
+{
+    private static function create(string $message, mixed $value): self
+    {
+        return new self(\sprintf($message, \var_export($value, true)));
+    }
+
+    public static function forInvalidType(mixed $value): self
+    {
+        return self::create('Value must be a Geometry value object, %s given', $value);
+    }
+
+    public static function forInvalidFormat(mixed $value): self
+    {
+        return self::create('Invalid Geometry value object format: %s', $value);
+    }
+}

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

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use MartinGeorgiev\Doctrine\DBAL\Types\Exceptions\InvalidGeographyForDatabaseException;
+use MartinGeorgiev\Doctrine\DBAL\Types\Exceptions\InvalidGeographyForPHPException;
+use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\Exceptions\InvalidWktSpatialDataException;
+use MartinGeorgiev\Doctrine\DBAL\Types\ValueObject\WktSpatialData;
+
+/**
+ * Implementation of PostGIS GEOGRAPHY data type.
+ *
+ * @see https://postgis.net/docs/using_postgis_dbmanagement.html
+ * @since 3.5
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+final class Geography extends BaseType
+{
+    protected const TYPE_NAME = 'geography';
+
+    public function convertToDatabaseValue($value, AbstractPlatform $platform): ?string
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        if (!$value instanceof WktSpatialData) {
+            throw InvalidGeographyForPHPException::forInvalidType($value);
+        }
+
+        return (string) $value;
+    }
+
+    public function convertToPHPValue($value, AbstractPlatform $platform): ?WktSpatialData
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        if (!\is_string($value)) {
+            throw InvalidGeographyForDatabaseException::forInvalidType($value);
+        }
+
+        try {
+            return WktSpatialData::fromWkt($value);
+        } catch (InvalidWktSpatialDataException) {
+            throw InvalidGeographyForDatabaseException::forInvalidFormat($value);
+        }
+    }
+}