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.

tests/Integration/README.md

@@ -1,27 +1,27 @@
 # PostgreSQL Integration Tests
 
-This directory contains integration tests that run against a real PostgreSQL database. These tests validate that our custom DBAL types work correctly with an actual PostgreSQL instance.
+This directory contains integration tests that run against a real PostgreSQL database with PostGIS extensions. These tests validate that our custom DBAL types work correctly with an actual PostgreSQL instance, including PostGIS geometry and geography types.
 
 ## Running Tests Locally
 
 ### Prerequisites
 
-- Docker (for running PostgreSQL)
+- Docker (for running PostgreSQL with PostGIS)
 - PHP 8.1+ with the `pdo_pgsql` extension
 
-### Start PostgreSQL
+### Start PostgreSQL with PostGIS
 
-You can use Docker Compose to start PostgreSQL:
+You can use Docker Compose to start PostgreSQL with PostGIS:
 
 ```bash
-# Start PostgreSQL using Docker Compose
+# Start PostgreSQL with PostGIS using Docker Compose
 docker-compose up -d
 ```
 
 Or use a plain Docker command:
 
 ```bash
-docker run --name postgres-doctrine-test -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres -e POSTGRES_DB=postgres_doctrine_test -p 5432:5432 -d postgres:17
+docker run --name postgres-doctrine-test -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres -e POSTGRES_DB=postgres_doctrine_test -p 5432:5432 -d postgis/postgis:17-3.4
 ```
 
 ### Run the Tests
@@ -66,6 +66,6 @@ docker rm postgres-doctrine-test
 
 ## CI Integration
 
-These tests are automatically run in GitHub Actions against PostgreSQL 16 and 17 for all supported PHP versions.
+These tests are automatically run in GitHub Actions against PostgreSQL 16 and 17 with PostGIS 3.4 for all supported PHP versions.
 
 The workflow is defined in `.github/workflows/integration-tests.yml`.