Doctrine ORM — Data Mapper for PHP and MySQL/PostgreSQL

Introduction

Doctrine ORM is the standard object-relational mapping library for PHP. It maps PHP objects to database tables using the Data Mapper pattern, keeping domain logic separate from persistence concerns. Doctrine supports MySQL, PostgreSQL, SQLite, and SQL Server, and is the default ORM in Symfony and widely used across the PHP ecosystem.

What Doctrine ORM Does

• Maps PHP classes to database tables using annotations, attributes, XML, or YAML metadata
• Provides DQL (Doctrine Query Language), an object-oriented query language similar to SQL but operating on entities and their relationships
• Manages entity lifecycle with a Unit of Work that batches inserts, updates, and deletes into optimized transactions
• Handles lazy loading, eager loading, and proxy generation for associated entities
• Generates and executes database migrations through the Doctrine Migrations companion library

Architecture Overview

Doctrine ORM is built on three layers: DBAL (Database Abstraction Layer) for connection management and SQL generation, the ORM core implementing the Unit of Work and Identity Map patterns, and the metadata layer that reads class mappings from attributes or configuration files. When an entity is persisted, the Unit of Work tracks changes and computes a changeset at flush time, issuing only the minimal SQL needed. The Identity Map ensures each database row maps to exactly one PHP object instance within a request, preventing inconsistencies.

Self-Hosting & Configuration

• Install via Composer and configure the connection parameters (driver, host, database, user, password) in a PHP bootstrap or Symfony config
• Define entity mappings using PHP 8 attributes, DocBlock annotations, or external XML/YAML files
• Generate the database schema with vendor/bin/doctrine orm:schema-tool:create or manage changes with Doctrine Migrations
• Configure caching (APCu, Redis, Memcached) for metadata, query, and result caches to improve performance in production
• Integrate with Symfony via DoctrineBundle for automatic entity manager injection, console commands, and profiler integration

Key Features

• Data Mapper pattern keeps domain objects free of persistence logic
• DQL provides type-safe, object-oriented querying with support for joins, aggregates, and subqueries
• Unit of Work batches database operations for transactional consistency and performance
• Second-level cache support for reducing database load on read-heavy applications
• Extensive event system with lifecycle callbacks and listeners for audit logging, soft deletes, and more

Comparison with Similar Tools

• Eloquent (Laravel) — Active Record pattern; simpler but couples domain objects to the database layer. Doctrine keeps them separate.
• Propel — another PHP ORM using Active Record; less actively maintained than Doctrine
• CakePHP ORM — tightly coupled to the CakePHP framework; Doctrine is framework-agnostic
• SQLAlchemy (Python) — similar Data Mapper approach for Python; Doctrine is the PHP equivalent
• TypeORM (TypeScript) — inspired by Doctrine; provides a similar experience for the Node.js ecosystem

FAQ

Q: Does Doctrine ORM work outside of Symfony? A: Yes. Doctrine is framework-agnostic and can be used standalone or with any PHP framework including Laravel, Laminas, and Slim.

Q: How does Doctrine handle database migrations? A: The companion library doctrine/migrations generates migration files by diffing the current schema against entity metadata, then runs them sequentially with version tracking.

Q: What is the performance overhead of using Doctrine? A: The Unit of Work adds some overhead per request, but metadata caching, second-level result caching, and DQL optimizations keep it performant for most workloads.

Q: Can Doctrine map to existing legacy database schemas? A: Yes. Mapping files can be configured to match any existing table and column naming convention without requiring schema changes.

Sources

• https://github.com/doctrine/orm
• https://www.doctrine-project.org/projects/orm.html