Change Tracking Policies ======================== Change tracking is the process of determining what has changed in managed entities since the last time they were synchronized with the database. Doctrine provides 3 different change tracking policies, each having its particular advantages and disadvantages. The change tracking policy can be defined on a per-class basis (or more precisely, per-hierarchy). Deferred Implicit ~~~~~~~~~~~~~~~~~ The deferred implicit policy is the default change tracking policy and the most convenient one. With this policy, Doctrine detects the changes by a property-by-property comparison at commit time and also detects changes to entities or new entities that are referenced by other managed entities ("persistence by reachability"). Although the most convenient policy, it can have negative effects on performance if you are dealing with large units of work (see "Understanding the Unit of Work"). Since Doctrine can't know what has changed, it needs to check all managed entities for changes every time you invoke EntityManager#flush(), making this operation rather costly. Deferred Explicit ~~~~~~~~~~~~~~~~~ The deferred explicit policy is similar to the deferred implicit policy in that it detects changes through a property-by-property comparison at commit time. The difference is that Doctrine 2 only considers entities that have been explicitly marked for change detection through a call to EntityManager#persist(entity) or through a save cascade. All other entities are skipped. This policy therefore gives improved performance for larger units of work while sacrificing the behavior of "automatic dirty checking". Therefore, flush() operations are potentially cheaper with this policy. The negative aspect this has is that if you have a rather large application and you pass your objects through several layers for processing purposes and business tasks you may need to track yourself which entities have changed on the way so you can pass them to EntityManager#persist(). This policy can be configured as follows: .. code-block:: php _listeners[] = $listener; } } Then, in each property setter of this class or derived classes, you need to notify all the ``PropertyChangedListener`` instances. As an example we add a convenience method on ``MyEntity`` that shows this behaviour: .. code-block:: php _listeners) { foreach ($this->_listeners as $listener) { $listener->propertyChanged($this, $propName, $oldValue, $newValue); } } } public function setData($data) { if ($data != $this->data) { $this->_onPropertyChanged('data', $this->data, $data); $this->data = $data; } } } You have to invoke ``_onPropertyChanged`` inside every method that changes the persistent state of ``MyEntity``. The check whether the new value is different from the old one is not mandatory but recommended. That way you also have full control over when you consider a property changed. The negative point of this policy is obvious: You need implement an interface and write some plumbing code. But also note that we tried hard to keep this notification functionality abstract. Strictly speaking, it has nothing to do with the persistence layer and the Doctrine ORM or DBAL. You may find that property notification events come in handy in many other scenarios as well. As mentioned earlier, the ``Doctrine\Common`` namespace is not that evil and consists solely of very small classes and interfaces that have almost no external dependencies (none to the DBAL and none to the ORM) and that you can easily take with you should you want to swap out the persistence layer. This change tracking policy does not introduce a dependency on the Doctrine DBAL/ORM or the persistence layer. The positive point and main advantage of this policy is its effectiveness. It has the best performance characteristics of the 3 policies with larger units of work and a flush() operation is very cheap when nothing has changed. Limitations and Known Issues ============================ We try to make using Doctrine2 a very pleasant experience. Therefore we think it is very important to be honest about the current limitations to our users. Much like every other piece of software Doctrine2 is not perfect and far from feature complete. This section should give you an overview of current limitations of Doctrine 2 as well as critical known issues that you should know about. Current Limitations ------------------- There is a set of limitations that exist currently which might be solved in the future. Any of this limitations now stated has at least one ticket in the Tracker and is discussed for future releases. Join-Columns with non-primary keys ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is not possible to use join columns pointing to non-primary keys. Doctrine will think these are the primary keys and create lazy-loading proxies with the data, which can lead to unexpected results. Doctrine can for performance reasons not validate the correctness of this settings at runtime but only through the Validate Schema command. Mapping Arrays to a Join Table ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Related to the previous limitation with "Foreign Keys as Identifier" you might be interested in mapping the same table structure as given above to an array. However this is not yet possible either. See the following example: .. code-block:: sql CREATE TABLE product ( id INTEGER, name VARCHAR, PRIMARY KEY(id) ); CREATE TABLE product_attributes ( product_id INTEGER, attribute_name VARCHAR, attribute_value VARCHAR, PRIMARY KEY (product_id, attribute_name) ); This schema should be mapped to a Product Entity as follows: .. code-block:: php class Product { private $id; private $name; private $attributes = array(); } Where the ``attribute_name`` column contains the key and ``attribute_value`` contains the value of each array element in ``$attributes``. The feature request for persistence of primitive value arrays `is described in the DDC-298 ticket `_. Value Objects ~~~~~~~~~~~~~ There is currently no native support value objects in Doctrine other than for ``DateTime`` instances or if you serialize the objects using ``serialize()/deserialize()`` which the DBAL Type "object" supports. The feature request for full value-object support `is described in the DDC-93 ticket `_. Cascade Merge with Bi-directional Associations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are two bugs now that concern the use of cascade merge in combination with bi-directional associations. Make sure to study the behavior of cascade merge if you are using it: - `DDC-875 `_ Merge can sometimes add the same entity twice into a collection - `DDC-763 `_ Cascade merge on associated entities can insert too many rows through "Persistence by Reachability" Custom Persisters ~~~~~~~~~~~~~~~~~ A Persister in Doctrine is an object that is responsible for the hydration and write operations of an entity against the database. Currently there is no way to overwrite the persister implementation for a given entity, however there are several use-cases that can benefit from custom persister implementations: - `Add Upsert Support `_ - `Evaluate possible ways in which stored-procedures can be used `_ - The previous Filter Rules Feature Request Persist Keys of Collections ~~~~~~~~~~~~~~~~~~~~~~~~~~~ PHP Arrays are ordered hash-maps and so should be the ``Doctrine\Common\Collections\Collection`` interface. We plan to evaluate a feature that optionally persists and hydrates the keys of a Collection instance. `Ticket DDC-213 `_ Mapping many tables to one entity ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is not possible to map several equally looking tables onto one entity. For example if you have a production and an archive table of a certain business concept then you cannot have both tables map to the same entity. Behaviors ~~~~~~~~~ Doctrine 2 will **never** include a behavior system like Doctrine 1 in the core library. We don't think behaviors add more value than they cost pain and debugging hell. Please see the many different blog posts we have written on this topics: - `Doctrine2 "Behaviors" in a Nutshell `_ - `A re-usable Versionable behavior for Doctrine2 `_ - `Write your own ORM on top of Doctrine2 `_ - `Doctrine 2 Behavioral Extensions `_ - `Doctrator _ Doctrine 2 has enough hooks and extension points so that **you** can add whatever you want on top of it. None of this will ever become core functionality of Doctrine2 however, you will have to rely on third party extensions for magical behaviors. Nested Set ~~~~~~~~~~ NestedSet was offered as a behavior in Doctrine 1 and will not be included in the core of Doctrine 2. However there are already two extensions out there that offer support for Nested Set with Doctrine 2: - `Doctrine2 Hierarchical-Structural Behavior `_ - `Doctrine2 NestedSet `_ Known Issues ------------ The Known Issues section describes critical/blocker bugs and other issues that are either complicated to fix, not fixable due to backwards compatibility issues or where no simple fix exists (yet). We don't plan to add every bug in the tracker there, just those issues that can potentially cause nightmares or pain of any sort. See the Open Bugs on Jira for more details on `bugs, improvement and feature requests `_. Identifier Quoting and Legacy Databases ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For compatibility reasons between all the supported vendors and edge case problems Doctrine 2 does **NOT** do automatic identifier quoting. This can lead to problems when trying to get legacy-databases to work with Doctrine 2. - You can quote column-names as described in the :doc:`Basic-Mapping ` section. - You cannot quote join column names. - You cannot use non [a-zA-Z0-9\_]+ characters, they will break several SQL statements. Having problems with these kind of column names? Many databases support all CRUD operations on views that semantically map to certain tables. You can create views for all your problematic tables and column names to avoid the legacy quoting nightmare. Microsoft SQL Server and Doctrine "datetime" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Doctrine assumes that you use ``DateTime2`` data-types. If your legacy database contains DateTime datatypes then you have to add your own data-type (see Basic Mapping for an example).