Doctrine
  • Projects
    ORM DBAL MongoDB ODM Coding Standard Collections Common Data fixtures Event Manager Inflector Instantiator Lexer Migrations PHPCR ODM Persistence RST Parser View All
  • Development
    Community Contributor Workflow Maintainer Workflow Contribute to Website Policies GitHub Styleguide
  • Sponsorship
  • Partners
  • Blog
Edit

Tutorials

  • Getting Started with Doctrine
    • Guide Assumptions
    • What is Doctrine?
      • What are Entities?
    • An Example Model: Bug Tracker
    • Project Setup
    • Obtaining the EntityManager
    • Generating the Database Schema
    • Starting with the Product Entity
      • Adding behavior to Entities
    • Adding Bug and User Entities
    • Implementing more Requirements
    • Queries for Application Use-Cases
      • List of Bugs
      • Array Hydration of the Bug List
      • Find by Primary Key
    • Dashboard of the User
    • Number of Bugs
    • Updating Entities
    • Entity Repositories
    • Conclusion
  • Getting Started: Database First
  • Getting Started: Model First
  • Working with Indexed Associations
    • Mapping Indexed Associations
    • Querying indexed associations
    • Outlook into the Future
  • Extra Lazy Associations
    • Enabling Extra-Lazy Associations
  • Composite and Foreign Keys as Primary Key
    • General Considerations
    • Primitive Types only
    • Identity through foreign Entities
    • Use-Case 1: Dynamic Attributes
    • Use-Case 2: Simple Derived Identity
    • Use-Case 3: Join-Table with Metadata
    • Performance Considerations
  • Ordering To-Many Associations
  • Override Field Association Mappings In Subclasses
  • Pagination
  • Separating Concerns using Embeddables
    • Initializing embeddables
    • Column Prefixing
    • DQL

Reference

  • Architecture
    • Using an Object-Relational Mapper
    • Requirements
    • Doctrine ORM Packages
      • Collection, Event Manager and Persistence
      • The DBAL Package
      • The ORM Package
    • Terminology
      • Entities
      • Mapped Superclasses
      • Transient Classes
      • Entity states
      • Persistent fields
      • Serializing entities
      • The EntityManager
      • Transactional write-behind
      • The Unit of Work
  • Installation and Configuration
    • Class loading
    • Obtaining an EntityManager
    • Setting up the Commandline Tool
  • Frequently Asked Questions
    • Database Schema
      • How do I set the charset and collation for MySQL tables?
    • Entity Classes
      • How can I add default values to a column?
    • Mapping
      • Why do I get exceptions about unique constraint failures during $em->flush()?
    • Associations
      • What is wrong when I get an InvalidArgumentException "A new entity was found through the relationship.."?
      • How can I filter an association?
      • I call clear() on a One-To-Many collection but the entities are not deleted
      • How can I add columns to a many-to-many table?
      • How can i paginate fetch-joined collections?
      • Why does pagination not work correctly with fetch joins?
    • Inheritance
      • Can I use Inheritance with Doctrine ORM?
      • Why does Doctrine not create proxy objects for my inheritance hierarchy?
    • EntityGenerator
      • Why does the EntityGenerator not do X?
      • Why does the EntityGenerator not generate inheritance correctly?
    • Performance
      • Why is an extra SQL query executed every time I fetch an entity with a one-to-one relation?
    • Doctrine Query Language
      • What is DQL?
      • Can I sort by a function (for example ORDER BY RAND()) in DQL?
      • Is it better to write DQL or to generate it with the query builder?
    • A Query fails, how can I debug it?
  • Basic Mapping
    • Creating Classes for the Database
    • Property Mapping
      • PHP Types Mapping
    • Doctrine Mapping Types
    • Identifiers / Primary Keys
      • Identifier Generation Strategies
        • Sequence Generator
      • Composite Keys
    • Quoting Reserved Words
  • Association Mapping
    • Many-To-One, Unidirectional
    • One-To-One, Unidirectional
    • One-To-One, Bidirectional
    • One-To-One, Self-referencing
    • One-To-Many, Bidirectional
    • One-To-Many, Unidirectional with Join Table
    • One-To-Many, Self-referencing
    • Many-To-Many, Unidirectional
    • Many-To-Many, Bidirectional
      • Owning and Inverse Side on a ManyToMany Association
    • Many-To-Many, Self-referencing
    • Mapping Defaults
    • Collections
    • Initializing Collections
  • Inheritance Mapping
    • Mapped Superclasses
    • Entity Inheritance
      • Performance impact on to-one associations
    • Single Table Inheritance
      • Design-time considerations
      • Performance impact
      • SQL Schema considerations
    • Class Table Inheritance
      • Design-time considerations
      • Performance impact
      • SQL Schema considerations
    • Overrides
      • Association Override
      • Attribute Override
    • Query the Type
  • Working with Objects
    • Entities and the Identity Map
    • Entity Object Graph Traversal
    • Persisting entities
    • Removing entities
      • Join-table management when removing from many-to-many collections
      • Performance of different deletion strategies
    • Detaching entities
    • Merging entities
    • Synchronization with the Database
      • Effects of Database and UnitOfWork being Out-Of-Sync
      • Synchronizing New and Managed Entities
      • Synchronizing Removed Entities
      • The size of a Unit of Work
      • The cost of flushing
      • Direct access to a Unit of Work
      • Entity State
    • Querying
      • By Primary Key
      • By Simple Conditions
      • By Criteria
      • By Eager Loading
      • By Lazy Loading
      • By DQL
      • By Native Queries
      • Custom Repositories
  • Working with Associations
    • Association Example Entities
    • Establishing Associations
    • Removing Associations
    • Association Management Methods
    • Synchronizing Bidirectional Collections
    • Transitive persistence / Cascade Operations
      • Persistence by Reachability: Cascade Persist
    • Orphan Removal
    • Filtering Collections
  • Implementing a TypedFieldMapper
    • DefaultTypedFieldMapper
    • TypedFieldMapper interface
    • ChainTypedFieldMapper
    • Implementing a TypedFieldMapper
  • Events
    • The Event System
      • Registering Event Handlers
    • Events Overview
      • Naming convention
    • Lifecycle Callbacks
    • Lifecycle Callbacks Event Argument
    • Listening and subscribing to Lifecycle Events
    • Implementing Event Listeners
      • prePersist
      • preRemove
      • preFlush
      • onFlush
      • postFlush
      • preUpdate
      • postUpdate, postRemove, postPersist
      • postLoad
      • onClear
    • Entity listeners
      • Entity listeners class
      • Entity listeners resolver
    • Load ClassMetadata Event
    • SchemaTool Events
      • postGenerateSchemaTable
      • postGenerateSchema
  • Doctrine Internals explained
    • How Doctrine keeps track of Objects
    • How Doctrine Detects Changes
    • Query Internals
    • The different ORM Layers
      • Hydration
      • Persisters
      • UnitOfWork
      • ResultSetMapping
      • DQL Parser
      • SQLWalker
      • EntityManager
      • ClassMetadataFactory
  • Association Updates: Owning Side and Inverse Side
    • Bidirectional Associations
    • Important concepts
  • Transactions and Concurrency
    • Transaction Demarcation
      • Approach 1: Implicitly
      • Approach 2: Explicitly
      • Exception Handling
    • Locking Support
      • Optimistic Locking
        • Important Implementation Notes
      • Pessimistic Locking
  • Batch Processing
    • Bulk Inserts
    • Bulk Updates
      • DQL UPDATE
      • Iterating results
    • Bulk Deletes
      • DQL DELETE
      • Iterating results
    • Iterating Large Results for Data-Processing
  • Doctrine Query Language
    • Types of DQL queries
    • SELECT queries
      • DQL SELECT clause
      • Result format
      • Joins
      • Named and Positional Parameters
      • DQL SELECT Examples
        • Partial Object Syntax
        • "NEW" Operator Syntax
      • Using INDEX BY
    • UPDATE queries
    • DELETE queries
    • Comments in queries
    • Functions, Operators, Aggregates
      • DQL Functions
      • Arithmetic operators
      • Aggregate Functions
      • Other Expressions
      • Adding your own functions to the DQL language
    • Querying Inherited Classes
      • Single Table
      • Class Table Inheritance
    • The Query class
      • Query Result Formats (Hydration Modes)
        • getResult()
        • getArrayResult()
        • getScalarResult()
        • getSingleScalarResult()
        • getSingleColumnResult()
        • getSingleResult()
        • getOneOrNullResult()
        • Custom Hydration Modes
      • Pure and Mixed Results
      • Fetching Multiple FROM Entities
      • Iterating Large Result Sets
      • Functions
        • Parameters
        • Cache related API
        • Query Hints
        • Query Cache (DQL Query Only)
        • First and Max Result Items (DQL Query Only)
        • Temporarily change fetch mode in DQL
    • EBNF
      • Document syntax:
      • Terminals
      • Query Language
      • Statements
      • Identifiers
      • Path Expressions
      • Clauses
      • Items
      • From, Join and Index by
      • Select Expressions
      • Conditional Expressions
      • Collection Expressions
      • Literal Values
      • Input Parameter
      • Arithmetic Expressions
      • Scalar and Type Expressions
      • Aggregate Expressions
      • Case Expressions
      • Other Expressions
      • Functions
  • The QueryBuilder
    • Constructing a new QueryBuilder object
    • Working with QueryBuilder
      • High level API methods
      • Binding parameters to your query
      • Limiting the Result
      • Executing a Query
      • The Expr class
      • Adding a Criteria to a Query
      • Low Level API
      • Expr* classes
  • Native SQL
    • The NativeQuery class
    • ResultSetMappingBuilder
    • The ResultSetMapping
      • Entity results
      • Joined entity results
      • Field results
      • Scalar results
        • Special case: DTOs
      • Meta results
      • Discriminator Column
      • Examples
    • Named Native Query
  • Change Tracking Policies
    • Deferred Implicit
    • Deferred Explicit
    • Notify
  • Partial Objects
    • What is the problem?
    • When should I force partial objects?
  • Annotations Reference
    • Index
    • Reference
      • @Column
      • @ColumnResult
      • @Cache
      • @ChangeTrackingPolicy
      • @CustomIdGenerator
      • @DiscriminatorColumn
      • @DiscriminatorMap
      • @Embeddable
      • @Embedded
      • @Entity
      • @EntityResult
      • @FieldResult
      • @GeneratedValue
      • @HasLifecycleCallbacks
      • @Index
      • @Id
      • @InheritanceType
      • @JoinColumn
      • @JoinColumns
      • @JoinTable
      • @ManyToOne
      • @ManyToMany
      • @MappedSuperclass
      • @NamedNativeQuery
      • @OneToOne
      • @OneToMany
      • @OrderBy
      • @PostLoad
      • @PostPersist
      • @PostRemove
      • @PostUpdate
      • @PrePersist
      • @PreRemove
      • @PreUpdate
      • @SequenceGenerator
      • @SqlResultSetMapping
      • @Table
      • @UniqueConstraint
      • @Version
  • Attributes Reference
    • Index
    • Reference
      • #[AssociationOverride]
      • #[AttributeOverride]
      • #[Column]
      • #[Cache]
      • #[ChangeTrackingPolicy]
      • #[CustomIdGenerator]
      • #[DiscriminatorColumn]
      • #[DiscriminatorMap]
      • #[Embeddable]
      • #[Embedded]
      • #[Entity]
      • #[GeneratedValue]
      • #[HasLifecycleCallbacks]
      • #[Index]
      • #[Id]
      • #[InheritanceType]
      • #[JoinColumn], #[InverseJoinColumn]
      • #[JoinTable]
      • #[ManyToOne]
      • #[ManyToMany]
      • #[MappedSuperclass]
      • #[OneToOne]
      • #[OneToMany]
      • #[OrderBy]
      • #[PostLoad]
      • #[PostPersist]
      • #[PostRemove]
      • #[PostUpdate]
      • #[PrePersist]
      • #[PreRemove]
      • #[PreUpdate]
      • #[SequenceGenerator]
      • #[Table]
      • #[UniqueConstraint]
      • #[Version]
  • XML Mapping
    • Simplified XML Driver
      • Example
      • XML-Element Reference
    • Defining an Entity
    • Defining Fields
    • Defining Identity and Generator Strategies
    • Defining a Mapped Superclass
    • Defining Inheritance Mappings
    • Defining Lifecycle Callbacks
    • Defining One-To-One Relations
    • Defining Many-To-One Associations
    • Defining One-To-Many Associations
    • Defining Many-To-Many Associations
    • Cascade Element
    • Join Column Element
    • Defining Order of To-Many Associations
    • Defining Indexes or Unique Constraints
    • Derived Entities ID syntax
  • YAML Mapping
    • Simplified YAML Driver
      • Example
    • Reference
      • Unique Constraints
  • PHP Mapping
    • PHP Files
    • Static Function
    • ClassMetadataBuilder
    • ClassMetadata API
      • General Setters
      • Inheritance Setters
      • Field Mapping Setters
      • Lifecycle Callback Setters
      • Versioning Setters
      • General Getters
      • Identifier Getters
      • Inheritance Getters
      • Change Tracking Getters
      • Field & Association Getters
      • Lifecycle Callback Getters
      • Runtime reflection methods
  • Caching
    • Types of Caches
      • Query Cache
      • Result Cache
      • Metadata Cache
    • Clearing the Cache
    • Cache Chaining
    • Cache Slams
  • Improving Performance
    • Bytecode Cache
    • Metadata and Query caches
    • Alternative Query Result Formats
    • Read-Only Entities
    • Extra-Lazy Collections
    • Temporarily change fetch mode in DQL
    • Apply Best Practices
    • Change Tracking policies
  • Tools
    • Doctrine Console
      • Setting Up the Console
      • Display Help Information
      • Command Overview
    • Database Schema Generation
    • Entity Generation
    • Convert Mapping Information
    • Reverse Engineering
    • Runtime vs Development Mapping Validation
    • Adding own commands
    • Re-use console application
  • Metadata Drivers
    • Core Metadata Drivers
    • Implementing Metadata Drivers
    • ClassMetadata
    • Getting ClassMetadata Instances
  • Best Practices
    • Constrain relationships as much as possible
    • Avoid composite keys
    • Use events judiciously
    • Use cascades judiciously
    • Don't use special characters
    • Don't use identifier quoting
    • Initialize collections in the constructor
    • Don't map foreign keys to fields in an entity
    • Use explicit transaction demarcation
  • Limitations and Known Issues
    • Current Limitations
      • Join-Columns with non-primary keys
      • Mapping Arrays to a Join Table
      • Cascade Merge with Bi-directional Associations
      • Custom Persisters
      • Persist Keys of Collections
      • Mapping many tables to one entity
      • Behaviors
      • Nested Set
      • Using Traits in Entity Classes
      • Mapping multiple private fields of the same name
    • Known Issues
      • Identifier Quoting and Legacy Databases
      • Microsoft SQL Server and Doctrine "datetime"
      • MySQL with MyISAM tables
  • Pagination
  • Filters
    • Example filter class
    • Configuration
    • Disabling/Enabling Filters and Setting Parameters
    • Suspending/Restoring Filters
  • Implementing a NamingStrategy
    • Configuring a naming strategy
    • Underscore naming strategy
    • Naming strategy interface
    • Implementing a naming strategy
  • Advanced Configuration
    • Doctrine and Caching
    • Configuration Options
      • Proxy Directory (REQUIRED)
      • Proxy Namespace (REQUIRED)
      • Metadata Driver (REQUIRED)
      • Metadata Cache (RECOMMENDED)
      • Query Cache (RECOMMENDED)
      • SQL Logger (Optional)
      • Auto-generating Proxy Classes (OPTIONAL)
    • Development vs Production Configuration
    • Connection
    • Proxy Objects
      • Reference Proxies
      • Association proxies
      • Generating Proxy classes
    • Autoloading Proxies
    • Multiple Metadata Sources
    • Default Repository (OPTIONAL)
    • Ignoring entities (OPTIONAL)
    • Setting up the Console
  • The Second Level Cache
    • Caching Regions
    • Cache Regions
      • Cache region
      • Concurrent cache region
      • Timestamp region
    • Caching mode
      • Built-in cached persisters
    • Configuration
      • Enable Second Level Cache
      • Cache Factory
      • Region Lifetime
      • Cache Log
    • Entity cache definition
    • Association cache definition
      • Cache usage
    • Using the query cache
      • Cache mode
      • DELETE / UPDATE queries
    • Using the repository query cache
    • Cache API
    • Limitations
      • Composite primary key
      • Distributed environments
      • Paginator
  • Security
    • User input and Doctrine ORM
    • Preventing Mass Assignment Vulnerabilities

Cookbook

  • Aggregate Fields
    • An example model
    • Using DQL
    • Using your Domain Model
    • Using an Aggregate Field
    • Tackling Race Conditions with Aggregate Fields
    • Keeping Updates and Deletes in Sync
    • Conclusion
  • Custom Mapping Types
  • Persisting the Decorator Pattern
    • Component
    • ConcreteComponent
    • Decorator
    • ConcreteDecorator
    • Examples
  • Extending DQL in Doctrine ORM: Custom AST Walkers
    • Generic count query for pagination
    • Modify the Output Walker to generate Vendor specific SQL
  • DQL User Defined Functions
    • Registering your own DQL functions
    • Date Diff
    • Date Add
    • Conclusion
  • Generated Columns
    • Declaring a generated column
    • Advanced example: Extracting a value from a JSON structure
  • Implementing ArrayAccess for Domain Objects
    • Option 1
    • Option 2
    • Read-only
  • Implementing the Notify ChangeTracking Policy
    • Implementing NotifyPropertyChanged
  • Keeping your Modules independent
    • Background
    • Set up
    • Final Thoughts
  • SQL-Table Prefixes
    • Implementing the listener
    • Telling the EntityManager about our listener
  • Strategy-Pattern
    • Scenario / Problem
    • Solution
  • Validation of Entities
  • Working with DateTime Instances
    • DateTime changes are detected by Reference
    • Default Timezone Gotcha
    • Handling different Timezones with the DateTime Type
  • Mysql Enums
    • Solution 1: Mapping to Varchars
    • Solution 2: Defining a Type
  • Advanced field value conversion using custom mapping types
    • The entity
    • The mapping type
    • Example usage
  • Entities in the Session
    • Updating an entity
      • Working with scalars
      • Working with custom data transfer objects
    • Serializing entity into the session
  1. Projects
  2. ORM
  3. Documentation
  4. Installation
2.20.3
Maintained
4.0 (upcoming) 3.4 (upcoming) 3.3.3 (current) 2.21 (upcoming) 2.20.3
Unmaintained
3.2 3.1 3.0 2.19 2.18 2.17 2.16 2.15 2.14 2.13 2.12 2.11 2.10

Installation

The installation chapter has moved to Installation and Configuration.