Deprecate NOTIFY change tracking policy

doctrine · May 2, 2022 · 6fd90ed · 6fd90ed
1 parent 44e7948
commit 6fd90ed
Show file tree

Hide file tree

Showing 6 changed files with 37 additions and 0 deletions.
diff --git a/UPGRADE-2.4.md b/UPGRADE-2.4.md
@@ -40,3 +40,9 @@ That method was inherited from the abstract `AnnotationDriver` class of
 Detaching all documents of a given class has been deprecated. We deem the process fragile and suggest
 detaching your documents one-by-one using `DocumentManager::detach()`. This effectively deprecates
 `OnClearEventArgs::getDocumentClass` and `OnClearEventArgs::clearsAllDocuments`.
+
+## Deprecate `NOTIFY` change tracking policy
+
+The `NOTIFY` change tracking policy has been deprecated. We suggest to use `DEFERRED_EXPLICIT`
+strategy instead. This effectively deprecates `ClassMetadata::isChangeTrackingNotify` and
+`ClassMetadata::CHANGETRACKING_NOTIFY`.
diff --git a/UPGRADE-3.0.md b/UPGRADE-3.0.md
@@ -22,6 +22,11 @@ The `boolean`, `integer`, and `int_id` mapping types have been removed. Use the
 `bool`, `int`, and `int` types, respectively. These types behave exactly the
 same.
 
+The `NOTIFY` change tracking policy has been removed, we suggest switching to
+`DEFERRED_EXPLICIT` instead. Consequentially `ClassMetadata::isChangeTrackingNotify` 
+and `ClassMetadata::CHANGETRACKING_NOTIFY` have been removed as well. `UnitOfWork`
+no longer implements the `PropertyChangedListener` interface.
+
 ## Proxy Class Name Resolution
 
 The `Doctrine\ODM\MongoDB\Proxy\Resolver\ClassNameResolver` interface has been

diff --git a/docs/en/cookbook/implementing-the-notify-changetracking-policy.rst b/docs/en/cookbook/implementing-the-notify-changetracking-policy.rst
@@ -10,6 +10,11 @@ code should look like. We will implement it on a
 `Layer Supertype <http://martinfowler.com/eaaCatalog/layerSupertype.html>`_
 for all our domain objects.
 
+.. warning::
+
+    The notify change tracking policy is deprecated and will be removed in ODM 3.0.
+    (`Details <https://github.com/doctrine/mongodb-odm/issues/2424>`_)
+
 Implementing NotifyPropertyChanged
 ----------------------------------
 

diff --git a/docs/en/reference/change-tracking-policies.rst b/docs/en/reference/change-tracking-policies.rst
@@ -62,6 +62,11 @@ This policy can be configured as follows:
 Notify
 ~~~~~~
 
+.. warning::
+
+    The notify change tracking policy is deprecated and will be removed in ODM 3.0.
+    (`Details <https://github.com/doctrine/mongodb-odm/issues/2424>`_)
+
 This policy is based on the assumption that the documents notify
 interested listeners of changes to their properties. For that
 purpose, a class that wants to use this policy needs to implement

diff --git a/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php b/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php
@@ -333,6 +333,8 @@
      * NOTIFY means that Doctrine relies on the entities sending out notifications
      * when their properties change. Such entity classes must implement
      * the <tt>NotifyPropertyChanged</tt> interface.
+     *
+     * @deprecated
      */
     public const CHANGETRACKING_NOTIFY = 3;
 
@@ -1316,6 +1318,9 @@ public function isChangeTrackingDeferredImplicit(): bool
 
     /**
      * Whether the change tracking policy of this class is "notify".
+     *
+     * @deprecated This method was deprecated in doctrine/mongodb-odm 2.4. Please use DEFERRED_EXPLICIT tracking
+     * policy and isChangeTrackingDeferredImplicit method to detect it.
      */
     public function isChangeTrackingNotify(): bool
     {

diff --git a/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadataFactory.php b/lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadataFactory.php
@@ -27,6 +27,7 @@
 use function get_class_methods;
 use function in_array;
 use function interface_exists;
+use function trigger_deprecation;
 use function ucfirst;
 
 /**
@@ -207,6 +208,16 @@ protected function doLoadMetadata($class, $parent, $rootEntityFound, array $nonS
 
         $eventArgs = new LoadClassMetadataEventArgs($class, $this->dm);
         $this->evm->dispatchEvent(Events::loadClassMetadata, $eventArgs);
+
+        // phpcs:ignore SlevomatCodingStandard.ControlStructures.EarlyExit.EarlyExitNotUsed
+        if ($class->isChangeTrackingNotify()) {
+            trigger_deprecation(
+                'doctrine/mongodb-odm',
+                '2.4',
+                'NOTIFY tracking policy used in class "%s" is deprecated. Please use DEFERRED_EXPLICIT instead.',
+                $class->name
+            );
+        }
     }
 
     /**