@@ -5,7 +5,7 @@ Change tracking is the process of determining what has changed in
55managed entities since the last time they were synchronized with
66the database.
77
8- Doctrine provides 3 different change tracking policies, each having
8+ Doctrine provides 2 different change tracking policies, each having
99its particular advantages and disadvantages. The change tracking
1010policy can be defined on a per-class basis (or more precisely,
1111per-hierarchy).
@@ -56,122 +56,3 @@ This policy can be configured as follows:
5656 {
5757 // ...
5858 }
59-
60-
61- ~~~~~~
62-
63- .. note ::
64-
65- The notify change tracking policy is deprecated and will be removed in ORM 3.0.
66- (`Details <https://github.com/doctrine/orm/issues/8383 >`_)
67-
68- This policy is based on the assumption that the entities notify
69- interested listeners of changes to their properties. For that
70- purpose, a class that wants to use this policy needs to implement
71- the ``NotifyPropertyChanged `` interface from the Doctrine
72- namespace. As a guideline, such an implementation can look as
73- follows:
74-
75- .. code-block :: php
76-
77- <?php
78- use Doctrine\Persistence\NotifyPropertyChanged,
79- Doctrine\Persistence\PropertyChangedListener;
80-
81- #[Entity]
82- #[ChangeTrackingPolicy('NOTIFY')]
83- class MyEntity implements NotifyPropertyChanged
84- {
85- // ...
86-
87- private array $_listeners = array();
88-
89- public function addPropertyChangedListener(PropertyChangedListener $listener): void
90- {
91- $this->_listeners[] = $listener;
92- }
93- }
94-
95-
96- need to notify all the ``PropertyChangedListener `` instances. As an
97- example we add a convenience method on ``MyEntity `` that shows this
98- behaviour:
99-
100- .. code-block :: php
101-
102- <?php
103- // ...
104-
105- class MyEntity implements NotifyPropertyChanged
106- {
107- // ...
108-
109- protected function _onPropertyChanged($propName, $oldValue, $newValue): void
110- {
111- if ($this->_listeners) {
112- foreach ($this->_listeners as $listener) {
113- $listener->propertyChanged($this, $propName, $oldValue, $newValue);
114- }
115- }
116- }
117-
118- public function setData($data): void
119- {
120- if ($data != $this->data) {
121- $this->_onPropertyChanged('data', $this->data, $data);
122- $this->data = $data;
123- }
124- }
125- }
126-
127- _onPropertyChanged `` inside every method that
128- changes the persistent state of ``MyEntity ``.
129-
130- The check whether the new value is different from the old one is
131- not mandatory but recommended. That way you also have full control
132- over when you consider a property changed.
133-
134- If your entity contains an embeddable, you will need to notify
135- separately for each property in the embeddable when it changes
136- for example:
137-
138- .. code-block :: php
139-
140- <?php
141- // ...
142-
143- class MyEntity implements NotifyPropertyChanged
144- {
145- public function setEmbeddable(MyValueObject $embeddable): void
146- {
147- if (!$embeddable->equals($this->embeddable)) {
148- // notice the entityField.embeddableField notation for referencing the property
149- $this->_onPropertyChanged('embeddable.prop1', $this->embeddable->getProp1(), $embeddable->getProp1());
150- $this->_onPropertyChanged('embeddable.prop2', $this->embeddable->getProp2(), $embeddable->getProp2());
151- $this->embeddable = $embeddable;
152- }
153- }
154- }
155-
156-
157- implement a diff method on your embedded object which returns only
158- the changed fields.
159-
160- The negative point of this policy is obvious: You need implement an
161- interface and write some plumbing code. But also note that we tried
162- hard to keep this notification functionality abstract. Strictly
163- speaking, it has nothing to do with the persistence layer and the
164- Doctrine ORM or DBAL. You may find that property notification
165- events come in handy in many other scenarios as well. As mentioned
166- earlier, the ``Doctrine\Common `` namespace is not that evil and
167- consists solely of very small classes and interfaces that have
168- almost no external dependencies (none to the DBAL and none to the
169- ORM) and that you can easily take with you should you want to swap
170- out the persistence layer. This change tracking policy does not
171- introduce a dependency on the Doctrine DBAL/ORM or the persistence
172- layer.
173-
174- The positive point and main advantage of this policy is its
175- effectiveness. It has the best performance characteristics of the 3
176- policies with larger units of work and a flush() operation is very
177- cheap when nothing has changed.
0 commit comments