diff --git a/UPGRADE-2.4.md b/UPGRADE-2.4.md index e3fb067781..471d8b1f14 100644 --- 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 index 2b7c5302e0..c52f94f6d0 100644 --- 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 index 867eb9633c..31c34934d7 100644 --- 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 `_ for all our domain objects. +.. warning:: + + The notify change tracking policy is deprecated and will be removed in ODM 3.0. + (`Details `_) + Implementing NotifyPropertyChanged ---------------------------------- diff --git a/docs/en/reference/change-tracking-policies.rst b/docs/en/reference/change-tracking-policies.rst index 5ea2179777..980b0d0371 100644 --- 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 `_) + 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 index fc33d8aaee..b2dbfa247c 100644 --- 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 NotifyPropertyChanged 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 index ee0679cbe2..f2619e4ff3 100644 --- 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 + ); + } } /**