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

Author: martin-georgiev

.github/workflows/integration-tests.yml

@@ -34,21 +34,23 @@ 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']
+        postgis: ['3.4', '3.5']
         postgres: ['16', '17']
         include:
           - php: '8.4'
+            postgis: '3.5'
             postgres: '17'
             calculate-code-coverage: true
 
     services:
       postgres:
-        image: postgres:${{ matrix.postgres }}
+        image: postgis/postgis:${{ matrix.postgres }}-${{ matrix.postgis }}
         env:
           POSTGRES_PASSWORD: postgres
           POSTGRES_USER: postgres
@@ -110,6 +112,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`, `geometry[]`)
+  - PostGIS Geography (`geography`, `geography[]`)
 - **Range Types**
   - Date and time ranges (`daterange`, `tsrange`, `tstzrange`)
   - Numeric ranges (`numrange`, `int4range`, `int8range`)
@@ -98,6 +100,8 @@ Full documentation:
 - [Value Objects for Range Types](docs/RANGE-TYPES.md)
 - [Available Functions and Operators](docs/AVAILABLE-FUNCTIONS-AND-OPERATORS.md)
 - [Common Use Cases and Examples](docs/USE-CASES-AND-EXAMPLES.md)
+- [Spatial Types](docs/SPATIAL-TYPES.md)
+- [Geometry Arrays](docs/GEOMETRY-ARRAYS.md)
 
 ## 📦 Installation
 
@@ -122,10 +126,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 +139,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
 

ci/php-cs-fixer/config.php

@@ -43,6 +43,7 @@
             'php_unit_internal_class' => false,
             'php_unit_method_casing' => ['case' => 'snake_case'],
             'php_unit_test_class_requires_covers' => false,
+            'phpdoc_align' => ['align' => 'left'],
             'phpdoc_types_order' => ['null_adjustment' => 'always_last'],
             'simplified_null_return' => false,
             'single_line_comment_style' => false,

devenv.nix

@@ -60,14 +60,37 @@ 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}';
+      -- Create role if it doesn't exist, or update password if it does
+      DO $$
+      BEGIN
+        IF NOT EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = '${config.env.POSTGRES_USER}') THEN
+          CREATE ROLE "${config.env.POSTGRES_USER}" WITH SUPERUSER LOGIN PASSWORD '${config.env.POSTGRES_PASSWORD}';
+        ELSE
+          ALTER ROLE "${config.env.POSTGRES_USER}" WITH SUPERUSER LOGIN PASSWORD '${config.env.POSTGRES_PASSWORD}';
+        END IF;
+      END
+      $$;
+
+      -- Set database owner
+      ALTER DATABASE "${config.env.POSTGRES_DB}" OWNER TO "${config.env.POSTGRES_USER}";
+
+      -- 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