Use custom lifecycle event classes for the soft-deleteable lifecycle events

Author: mbabker

CHANGELOG.md

@@ -21,10 +21,14 @@ a release.
 ### Changed
 - Dropped support for PHP < 7.4
 - Dropped support for Symfony < 5.4
+- ⚠️ [B/C Break] The `Gedmo\SoftDeleteable\SoftDeletableListener` dispatches events using the new `Gedmo\SoftDeleteable\Event\PreSoftDeleteEventArgs`
+  and `Gedmo\SoftDeleteable\Event\PostSoftDeleteEventArgs` classes, which directly extend from `Doctrine\Persistence\Event\LifecycleEventArgs`; previously,
+  each object manager's own lifecycle event args class was used.
 
 ### Deprecated
 - Calling `Gedmo\Mapping\Event\Adapter\ORM::getObjectManager()` and `getObject()` on EventArgs that do not implement `getObjectManager()` and `getObject()` (such as old EventArgs implementing `getEntityManager()` and `getEntity()`) 
-- Calling `Gedmo\Uploadable\Event\UploadableBaseEventArgs::getEntityManager()` and `getEntity()`. Call `getObjectManager()` and `getObject()` instead. 
+- Calling `Gedmo\Uploadable\Event\UploadableBaseEventArgs::getEntityManager()` and `getEntity()`. Call `getObjectManager()` and `getObject()` instead.
+- The `createLifecycleEventArgsInstance()` method on `Gedmo\Mapping\Event\AdapterInterface` implementations is deprecated, use your own subclass of `Doctrine\Persistence\Event\LifecycleEventArgs` as needed.
 
 ## [3.13.0] - 2023-09-06
 ### Fixed

src/Mapping/Event/Adapter/ODM.php

@@ -156,9 +156,16 @@ public function clearObjectChangeSet($uow, $object)
      * @param DocumentManager $documentManager
      *
      * @return LifecycleEventArgs
+     *
+     * @deprecated to be removed in 4.0, use custom lifecycle event classes instead
      */
     public function createLifecycleEventArgsInstance($document, $documentManager)
     {
+        @trigger_error(sprintf(
+            'Using "%s()" method is deprecated since gedmo/doctrine-extensions 3.14 and will be removed in version 4.0.',
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         return new LifecycleEventArgs($document, $documentManager);
     }
 }

src/Mapping/Event/Adapter/ORM.php

@@ -186,9 +186,20 @@ public function clearObjectChangeSet($uow, $object)
      * @param EntityManagerInterface $entityManager
      *
      * @return LifecycleEventArgs
+     *
+     * @deprecated Use custom lifecycle event classes instead
      */
     public function createLifecycleEventArgsInstance($document, $entityManager)
     {
+        @trigger_error(sprintf(
+            'Using "%s()" method is deprecated since gedmo/doctrine-extensions 3.14 and will be removed in version 4.0.',
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
+        if (!class_exists(LifecycleEventArgs::class)) {
+            throw new \RuntimeException(sprintf('Cannot call %s() when using doctrine/orm >=3.0, use a custom lifecycle event class instead.', __METHOD__));
+        }
+
         return new LifecycleEventArgs($document, $entityManager);
     }
 }

src/SoftDeleteable/Event/PostSoftDeleteEventArgs.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the Doctrine Behavioral Extensions package.
+ * (c) Gediminas Morkevicius <[email protected]> http://www.gediminasm.org
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Gedmo\SoftDeleteable\Event;
+
+use Doctrine\Persistence\Event\LifecycleEventArgs;
+use Doctrine\Persistence\ObjectManager;
+
+/**
+ * Post soft-delete lifecycle event
+ *
+ * @extends LifecycleEventArgs<ObjectManager>
+ */
+final class PostSoftDeleteEventArgs extends LifecycleEventArgs
+{
+}

src/SoftDeleteable/Event/PreSoftDeleteEventArgs.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the Doctrine Behavioral Extensions package.
+ * (c) Gediminas Morkevicius <[email protected]> http://www.gediminasm.org
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Gedmo\SoftDeleteable\Event;
+
+use Doctrine\Persistence\Event\LifecycleEventArgs;
+use Doctrine\Persistence\ObjectManager;
+
+/**
+ * Pre soft-delete lifecycle event
+ *
+ * @extends LifecycleEventArgs<ObjectManager>
+ */
+final class PreSoftDeleteEventArgs extends LifecycleEventArgs
+{
+}

src/SoftDeleteable/SoftDeleteableListener.php

@@ -17,6 +17,8 @@
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\ObjectManager;
 use Gedmo\Mapping\MappedEventSubscriber;
+use Gedmo\SoftDeleteable\Event\PostSoftDeleteEventArgs;
+use Gedmo\SoftDeleteable\Event\PreSoftDeleteEventArgs;
 
 /**
  * SoftDeleteable listener
@@ -83,7 +85,7 @@ public function onFlush(EventArgs $args)
 
                 $evm->dispatchEvent(
                     self::PRE_SOFT_DELETE,
-                    $ea->createLifecycleEventArgsInstance($object, $om)
+                    new PreSoftDeleteEventArgs($object, $om)
                 );
 
                 $reflProp->setValue($object, $date);
@@ -100,7 +102,7 @@ public function onFlush(EventArgs $args)
 
                 $evm->dispatchEvent(
                     self::POST_SOFT_DELETE,
-                    $ea->createLifecycleEventArgsInstance($object, $om)
+                    new PostSoftDeleteEventArgs($object, $om)
                 );
             }
         }