repository·3.6.x·Indexed 27 days ago
https://github.com/doctrine/ormAn object-relational mapper for PHP 8.1+ that enables transparent persistence of PHP objects. Built on top of the Doctrine Database Abstraction Layer (DBAL), it features the Doctrine Query Language (DQL) for object-oriented querying. The documentation covers custom mapping types, aggregate field implementation, locking strategies (optimistic and pessimistic), and advanced patterns such as Single Table Inheritance for the Decorator pattern.
Doctrine ORM is an object-relational mapper for PHP 8.1+ that provides transparent persistence for PHP objects. It is built on top of the Doctrine Database Abstraction Layer (DBAL).
A key feature is Doctrine Query Language (DQL), a proprietary object-oriented SQL dialect inspired by Hibernate's HQL. DQL allows developers to write queries against the object model rather than the database schema, providing flexibility and reducing code duplication.
DQL (Doctrine Query Language) is an object-oriented query language used to query your domain model rather than your relational database schema.
Key concepts:
SELECT, UPDATE, and DELETE constructs.INSERT in DQL. To add new data, you must use EntityManager#persist() to ensure the object model and persistence context remain consistent.The Doctrine ORM documentation is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported (CC BY-NC-SA 3.0) license.
Under this license, you are free to:
However, you must comply with the following restrictions:
The EntityManager manages a UnitOfWork, which acts as an object-level transaction. A new UnitOfWork starts when an EntityManager is created or after EntityManager#flush() is called.
Key behaviors:
EntityManager#flush() executes write operations against the database. Methods like EntityManager#persist($entity) or EntityManager#remove($entity) only notify the UnitOfWork of intended changes.EntityManager#flush() commits the current UnitOfWork and starts a new one.EntityManager#close() manually closes the UnitOfWork. Any unpersisted changes in that UnitOfWork will be lost.You can modify the Doctrine Query Language (DQL) parsing process by hooking into the Abstract Syntax Tree (AST) using Custom Tree Walkers. There are two types of walkers:
SqlWalker). Use this to introduce vendor-specific SQL keywords or to modify the final SQL string (e.g., for debugging or interpolation).To register a walker, use the Query::setHint() method with the appropriate constant.
Doctrine ORM is composed of several decoupled packages. The ORM package depends on DBAL, Persistence, and Collections.
Doctrine\ORM): The object-relational mapping toolkit providing transparent relational persistence for plain PHP objects.Doctrine\DBAL): An enhanced database abstraction layer on top of PDO that provides a single API to bridge differences between RDBMS vendors.Doctrine\Persistence): Contains reusable components for persistence.Doctrine\Common\Collections): Contains reusable collection components.Doctrine\Common): Contains reusable event management components.Doctrine uses change tracking policies to determine which managed entities have changed since they were last synchronized with the database. You can define these policies on a per-class or per-hierarchy basis. There are two primary policies:
Deferred Implicit (Default): Doctrine performs a property-by-property comparison of all managed entities during EntityManager#flush(). It also supports "persistence by reachability," meaning it detects changes to entities or new entities referenced by other managed entities. While convenient, it can impact performance in large units of work because every managed entity must be checked.
Deferred Explicit: Similar to the implicit policy, it uses property-by-property comparison at commit time. However, Doctrine only checks entities that have been explicitly marked for change detection via EntityManager#persist(entity) or through a save cascade. This improves performance for large units of work but requires you to manually track and persist entities that have changed.
Associations in Doctrine are managed using standard PHP object references or collections of objects. Key concepts include:
EntityManager#flush().Doctrine\Common\Collections\Collection interface.The YamlDriver and SimpleYamlDriver have been removed in 3.0. You must migrate your metadata mapping to use attributes, annotations, or XML drivers.
If you are currently using YAML, you can use the orm:convert-mapping command to convert your metadata to XML before upgrading to 3.0:
php doctrine orm:convert-mapping xml /path/to/mapping-path-converted-to-xmlSupport for implicit joins via multi-dot/deep path expressions was removed in 2.0-BETA2. You must now use explicit joins.
Incorrect (Deep Path):
SELECT u FROM User u WHERE u.group.name = ?1Correct (Explicit Join):
SELECT u FROM User u JOIN u.group g WHERE g.name = ?1When you use disable($name), the filter instance is deleted and all previously set parameters are lost. If you re-enable it, it will be a fresh instance without parameters.
To temporarily disable a filter while keeping its parameters intact, use suspend($name) and restore($name):
suspend($name): Temporarily stops the filter from being applied but preserves its state.restore($name): Re-activates the suspended filter with its original parameters.<?php
$filter = $em->getFilters()->enable("locale");
$filter->setParameter('locale', 'en');
// Temporary suspend the filter
$filter = $em->getFilters()->suspend("locale");
// Do things
// Then restore it, the locale parameter will still be set
$filter = $em->getFilters()->restore("locale");