Doctrine Spatial project overview
Current version — This documentation describes the current major version of doctrine-spatial.
Release schedules, support dates and test matrices below preserve the collected snapshot; they are not live release metadata.
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.
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?
Collected roadmap and compatibility
[!NOTE] A major release may increase the minimum supported PHP version. Other breaking changes are documented in the changelog.
| Version | PHP compatibility | Tested on | Doctrine ORM | Tested against Doctrine ORM | Released | Active support | Security fixes |
|---|---|---|---|---|---|---|---|
| 5 | 8.1 - 8.2 - 8.3 - 8.4 - 8.5 | From 8.1 to 8.3 | ^2.1 - ^3.0 - ^4.0.x-dev | ^2.1 - ^3.0 - ^4.0.x-dev | 04 May 2024 | 31 August 2026 | 31 December 2026 |
| 6 | 8.4 - 8.5 | 8.4 - 8.5 | ^3.6 - ^4.0.x-dev | ^3.6 - ^4.0.x-dev | September 2026 | 31 December 2027 | 31 December 2028 |
| 7 | 8.4 - 8.5 | 8.4 - 8.5 | ^3.6 - ^4.0.x-dev | ^3.6 - ^4.0.x-dev | Unknown | Unknown | Unknown |
| 8 | 8.5 | 8.5 | ^3.6 - ^4.0.x-dev | January 2028 | 31 December 2028 | 31 December 2029 |
[!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
| Status | Doctrine Spatial | PHP | Doctrine ORM |
|---|---|---|---|
| Old-Stable (security fixes) | 5.0 | 8.1+ | ^2.9, ^3.1 |
| Stable (bug and security fix) | 6.0 | 8.4+ | ^3.6, ^4.x-dev |
| Next major version | 7.0 | 8.4+ | ^3.6, ^4.x-dev |
| Planned for 1 January 2028 | 8.0 | 8.5+ | ^3.6, ^4.x-dev |
Database testing
The CI workflow tests the current development branch against the following database server versions.
| Test job | PHP | MySQL | MariaDB | PostgreSQL | PostGIS | SQL Server |
|---|---|---|---|---|---|---|
| Minimum database versions | 8.4 | 8.4. | 10.11 | 15 | 3.5 | 2022. |
| Maximum database versions | 8.5 | 9.6 | 12.3. | 18 | 3.6 | 2025 |
These versions may change as the CI test matrix evolves.
Known limitations in the collected documentation
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.