Doctrine Spatial

Doctrine Spatial is a Doctrine ORM and DBAL extension for working with spatial data in PHP applications.

It provides support for spatial types and functions across multiple database engines, while keeping the integration close to Doctrine’s native entity and query model.

Why use it?

• Map geometry and geography data with Doctrine entities.
• Use spatial predicates and functions directly in DQL.
• Work with PostgreSQL/PostGIS, MySQL, MariaDB, and SQL Server.
• Keep database-specific behavior explicit and well documented.

Current status

Documentation

The documentation covers installation, configuration, entity mapping, spatial queries, and contribution guidelines.

It also includes a glossary for the main spatial types and functions supported by the library.

Examples

[!NOTE] The Doctrine-Spatial demo is a complete web application built with Symfony, Doctrine, and Doctrine-Spatial. It illustrates a concrete use case for spatial queries: are our superheroes really in Gotham City?

Roadmap

[!NOTE] A major release may increase the minimum supported PHP version. Other breaking changes are documented in the changelog.

[!NOTE] Why does PHP support jump between versions 5 and 6?

PHP 8.4 introduces lazy objects. Designed especially for Doctrine-created objects, this feature removes the need for proxies and dedicated proxy namespaces. This is a major change that improves performance. Maintaining a library that supports both approaches complicates development and maintenance. Version 5 of Doctrine Spatial provides a smooth transition: it is compatible with PHP 8.1 through 8.5 and with Doctrine ORM versions 2, 3, and even 4. You are encouraged to upgrade to PHP 8.4 and Doctrine ORM 3.6, which introduces lazy objects, before upgrading to Doctrine Spatial version 6. Version 6 contains no breaking changes other than higher minimum supported versions of PHP and Doctrine ORM.

Version 7 is planned as an intermediate release between versions 6 and 8, with the following new features:

• Support for Z (elevation) and M (measure) dimensions
• SRID support for MySQL and SQL Server
• A new library ecosystem, including doctrine-spatial-types, geo-parser version 4, and new writers

The release date will depend on the availability of contributors and on my ability to fund subscriptions to AI development tools. Donations of coffee through Ko-fi will go either towards actual coffee or towards AI subscriptions.

Release

Database testing

The CI workflow tests the current development branch against the following database server versions.

These versions may change as the CI test matrix evolves.

Known limitations

longitude-one/doctrine-spatial cannot currently persist SRIDs in MySQL or SQL Server. Internally, the extension uses Well-Known Text (WKT) to translate values to and from the database, but Doctrine’s persistence layer cannot pass a WKT value and an SRID together. Extended Well-Known Text (EWKT) addresses this limitation in PostGIS, but other database engines do not support it.

You can work around this limitation by using the ST_SetSRID and ST_SRID spatial functions when needed. This allows SRIDs to be handled at the query level, even though they are not stored directly with the value.

Contributing

Contributions, bug reports, and documentation improvements are welcome. Please refer to the documentation for the development workflow and test commands.

Branch strategy

The repository follows a structured release model:

• 5.0.x-dev — Security updates for 5.0.x only.
• main — No breaking changes; only the minimum supported versions of PHP and Doctrine ORM may change.
• 6.1.x-dev — New features without breaking changes.
• 7.0.x-dev — New features with breaking changes.