README

This library allows you to use Doctrine (ORM or DBAL) with PostGIS, the spatial database extension for PostgreSQL.

• Supported Versions
• Installation
• Setup
  • Symfony
• Property Mapping
• Spatial Indexes
• Schema Tool
• DQL Functions
• Known Problems
• Running the Tests

Supported Versions

The following table shows the versions which are officially supported by this library.

Installation

Install the latest version with Composer.

composer require jsor/doctrine-postgis

Check the Packagist page for all available versions.

Setup

Basic setup requires registering Middleware and the SchemaManagerFactory via the DBAL connection configuration.

use Doctrine\DBAL\Configuration;
use Doctrine\DBAL\Connection;
use Doctrine\DBAL\Driver\PgSQL\Driver;
use Jsor\Doctrine\PostGIS\Driver\Middleware;
use Jsor\Doctrine\PostGIS\Event\ORMSchemaEventListener;
use Jsor\Doctrine\PostGIS\Schema\SchemaManagerFactory;

$params = [
    // your connection parameters …
];
$config = new Configuration();
$config->setMiddlewares([new Middleware]);
$config->setSchemaManagerFactory(new SchemaManagerFactory());

$connection = new Connection($params, new Driver(), $config);

Additionally, to also use the library with the Doctrine ORM, register the ORMSchemaEventListener event subscriber.

use Doctrine\ORM\Tools\ToolEvents;
use Jsor\Doctrine\PostGIS\Event\ORMSchemaEventListener;

$entityManager->getEventManager()->addEventListener(ToolEvents::postGenerateSchemaTable, new ORMSchemaEventListener());

Symfony

For integrating this library into a Symfony project, read the dedicated Symfony Documentation.

Property Mapping

Once the event subscriber is registered, the column types geometry and geography can be used in property mappings (please read the PostGIS docs to understand the difference between these two types).

use Doctrine\ORM\Mapping as ORM;
use Jsor\Doctrine\PostGIS\Types\PostGISType;

#[ORM\Entity]
class MyEntity
{
    #[ORM\Column(type: PostGISType::GEOMETRY)]
    private string $geometry;

    #[ORM\Column(type: PostGISType::GEOGRAPHY)]
    private string $geography;
}

There are 2 options to configure the geometry.

• geometry_type This defines the type of the geometry, like POINT, LINESTRING etc. If you omit this option, the generic type GEOMETRY is used.
• srid This defines the Spatial Reference System Identifier (SRID) of the geometry.

Example

use Doctrine\ORM\Mapping as ORM;
use Jsor\Doctrine\PostGIS\Types\PostGISType;

#[ORM\Entity]
class MyEntity
{
    #[ORM\Column(
        type: PostGISType::GEOMETRY, 
        options: ['geometry_type' => 'POINT'],
    )]
    public string $point;

    #[ORM\Column(
        type: PostGISType::GEOMETRY, 
        options: ['geometry_type' => 'POINTZM'],
   )]
    public string $point4D;

    #[ORM\Column(
        type: PostGISType::GEOMETRY, 
        options: ['geometry_type' => 'POINT', 'srid' => 3785],
    )]
    public string $pointWithSRID;

    public function __construct(
        string $point,
        string $point4D,
        string $pointWithSRID,
    ) {
        $this->point = $point;
        $this->point4D = $point4D;
        $this->pointWithSRID = $pointWithSRID;
    }
}

Values provided for the properties must be in the WKT format. Please note, that the values returned from database may differ from the values you have set. The library uses ST_AsEWKT to retain as much information as possible (like SRID's). Read more in the PostGIS docs.

Example

$entity = new MyEntity(
    point: 'POINT(-122.0845187 37.4220761)',
    point4D: 'POINT(1 2 3 4)',
    pointWithSRID: 'SRID=3785;POINT(-122.0845187 37.4220761)',
);

Spatial Indexes

Spatial indexes can be defined for geometry fields by setting the spatial flag.

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Index(
    fields: ['pointWithSRID'],
    flags: ['spatial'],
)]
class MyEntity
{
}

Schema Tool

Full support for the ORM Schema Tool and the DBAL Schema Manager is provided.

DQL Functions

Most PostGIS functions are also available for the Doctrine Query Language (DQL) under the Jsor\Doctrine\PostGIS\Functions namespace.

For a full list of all supported functions, see the Function Index.

Read the dedicated Symfony documentation on how to configure the functions with Symfony.

The functions must be registered with the Doctrine\ORM\Configuration instance.

$configuration = new Doctrine\ORM\Configuration();

$configuration->addCustomStringFunction(
    'ST_Within',
    Jsor\Doctrine\PostGIS\Functions\ST_Within::class
);

$configuration->addCustomNumericFunction(
    'ST_Distance',
    Jsor\Doctrine\PostGIS\Functions\ST_Distance::class
);

$dbParams = [/***/];
$entityManager = Doctrine\ORM\EntityManager::create($dbParams, $configuration);

There's a convenience Configurator class which can be used to register all functions at once.

$configuration = new Doctrine\ORM\Configuration();

Jsor\Doctrine\PostGIS\Functions\Configurator::configure($configuration);

$dbParams = [/***/];
$entityManager = Doctrine\ORM\EntityManager::create($dbParams, $configuration);

Known Problems

Read the dedicated Symfony documentation on how to handle those problems with Symfony.

PostGIS Schema Exclusion

Since PostGIS can add a few new schemas, like topology, tiger and tiger_data, you might want to exclude them from being handled by Doctrine.

This can be done by configuring a schema assets filter.

$configuration = new Doctrine\ORM\Configuration();

$configuration->setSchemaAssetsFilter(static function ($assetName): bool {
     if ($assetName instanceof AbstractAsset) {
         $assetName = $assetName->getName();
     }

     return (bool) preg_match('/^(?!tiger)(?!topology)/', $assetName);
});

$dbParams = [/***/];
$entityManager = Doctrine\ORM\EntityManager::create($dbParams, $configuration);

Unknown Database Types

Sometimes, the schema tool stumbles upon database types it can't handle. A common exception is something like

Doctrine\DBAL\Exception: Unknown database type _text requested, Doctrine\DBAL\Platforms\PostgreSQL100Platform may not support it.

To solve this, the unknown database types can be mapped to known types.

$configuration = new Doctrine\ORM\Configuration();

$dbParams = [/***/];
$entityManager = Doctrine\ORM\EntityManager::create($dbParams, $configuration);

$entityManager->getConnection()->getDatabasePlatform()->registerDoctrineTypeMapping('_text', 'string');

Note: This type is then not suited to be used in entity mappings. It just prevents "Unknown database type..." exceptions thrown during database inspections by the schema tool.

If you want to use this type in your entities, you have to configure real database types, e.g. with the PostgreSQL for Doctrine package.

Running the Tests

A simple Docker setup is included to run the test suite against the different PostgreSQL / PostGIS combinations.

All commands here should be run from the project root.

First, build the PHP container. This must be done only once.

./docker/build-php.sh

Install dependencies via Composer.

./docker/run-php.sh composer install

Next, start the database containers.

docker compose -f ./docker/docker-compose.yml up -d

There are a number of shortcut scripts available to execute commands inside the PHP container connected to specific database containers.

The script names follow the pattern run-<POSTGRESQL_VERSION>-<POSTGIS_VERSION>.sh.

To run the test suite against PostgreSQL 18 with PostGIS 3.6, use the script ./docker/run-18-36.sh.

Tests are either PostGIS version specific (versioned) or agnostic, and are run separately using PHPUnit groups.

e.g. for PostGIS 3.6 and PostgreSQL 18

./docker/run-18-36.sh vendor/bin/phpunit --exclude-group=versioned
./docker/run-18-36.sh vendor/bin/phpunit --group=postgis-3.6

e.g. for PostGIS 3.2 and PostgreSQL 14

./docker/run-14-32.sh vendor/bin/phpunit --exclude-group=versioned
./docker/run-14-32.sh vendor/bin/phpunit --group=postgis-3.2

License

Copyright (c) 2014-2024 Jan Sorgalla. Released under the MIT License.