Document expected EventArgs subtypes in listeners (#2761)

* Document expected EventArgs subtypes in listeners

* Update src/Uploadable/UploadableListener.php

---------

Co-authored-by: Fran Moreno <[email protected]>

Author: mbabker

src/AbstractTrackingListener.php

@@ -14,7 +14,9 @@
 use Doctrine\ODM\MongoDB\DocumentManager;
 use Doctrine\ODM\MongoDB\Types\Type as TypeODM;
 use Doctrine\ORM\UnitOfWork;
+use Doctrine\Persistence\Event\LifecycleEventArgs;
 use Doctrine\Persistence\Event\LoadClassMetadataEventArgs;
+use Doctrine\Persistence\Event\ManagerEventArgs;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\NotifyPropertyChanged;
 use Doctrine\Persistence\ObjectManager;
@@ -60,6 +62,10 @@ public function loadClassMetadata(EventArgs $eventArgs)
     /**
      * Processes object updates when the manager is flushed.
      *
+     * @param ManagerEventArgs $args
+     *
+     * @phpstan-param ManagerEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function onFlush(EventArgs $args)
@@ -162,6 +168,10 @@ public function onFlush(EventArgs $args)
     /**
      * Processes updates when an object is persisted in the manager.
      *
+     * @param LifecycleEventArgs $args
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function prePersist(EventArgs $args)

src/Loggable/LoggableListener.php

@@ -11,7 +11,9 @@
 
 use Doctrine\Common\EventArgs;
 use Doctrine\ORM\Mapping\ClassMetadata as ORMClassMetadata;
+use Doctrine\Persistence\Event\LifecycleEventArgs;
 use Doctrine\Persistence\Event\LoadClassMetadataEventArgs;
+use Doctrine\Persistence\Event\ManagerEventArgs;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\ObjectManager;
 use Gedmo\Exception\InvalidArgumentException;
@@ -140,6 +142,10 @@ public function loadClassMetadata(EventArgs $eventArgs)
      * Checks for inserted object to update its logEntry
      * foreign key
      *
+     * @param LifecycleEventArgs $args
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function postPersist(EventArgs $args)
@@ -187,6 +193,10 @@ public function postPersist(EventArgs $args)
      * Looks for loggable objects being inserted or updated
      * for further processing
      *
+     * @param ManagerEventArgs $eventArgs
+     *
+     * @phpstan-param ManagerEventArgs<ObjectManager> $eventArgs
+     *
      * @return void
      */
     public function onFlush(EventArgs $eventArgs)

src/ReferenceIntegrity/ReferenceIntegrityListener.php

@@ -10,6 +10,7 @@
 namespace Gedmo\ReferenceIntegrity;
 
 use Doctrine\Common\EventArgs;
+use Doctrine\Persistence\Event\LifecycleEventArgs;
 use Doctrine\Persistence\Event\LoadClassMetadataEventArgs;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\ObjectManager;
@@ -56,6 +57,10 @@ public function loadClassMetadata(EventArgs $eventArgs)
      * Looks for referenced objects being removed
      * to nullify the relation or throw an exception
      *
+     * @param LifecycleEventArgs $args
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function preRemove(EventArgs $args)

src/References/ReferencesListener.php

@@ -11,6 +11,7 @@
 
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\EventArgs;
+use Doctrine\Persistence\Event\LifecycleEventArgs;
 use Doctrine\Persistence\Event\LoadClassMetadataEventArgs;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\ObjectManager;
@@ -74,6 +75,10 @@ public function loadClassMetadata(EventArgs $eventArgs)
     }
 
     /**
+     * @param LifecycleEventArgs $eventArgs
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $eventArgs
+     *
      * @return void
      */
     public function postLoad(EventArgs $eventArgs)
@@ -140,6 +145,10 @@ static function () use ($id, &$manager, $class, $identifier) {
     }
 
     /**
+     * @param LifecycleEventArgs $eventArgs
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $eventArgs
+     *
      * @return void
      */
     public function prePersist(EventArgs $eventArgs)
@@ -148,6 +157,10 @@ public function prePersist(EventArgs $eventArgs)
     }
 
     /**
+     * @param LifecycleEventArgs $eventArgs
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $eventArgs
+     *
      * @return void
      */
     public function preUpdate(EventArgs $eventArgs)
@@ -190,6 +203,10 @@ public function getManager($type)
     }
 
     /**
+     * @param LifecycleEventArgs $eventArgs
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $eventArgs
+     *
      * @return void
      */
     public function updateManyEmbedReferences(EventArgs $eventArgs)
@@ -237,6 +254,11 @@ protected function getNamespace()
         return __NAMESPACE__;
     }
 
+    /**
+     * @param LifecycleEventArgs $eventArgs
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $eventArgs
+     */
     private function updateReferences(EventArgs $eventArgs): void
     {
         $ea = $this->getEventAdapter($eventArgs);

src/Sluggable/SluggableListener.php

@@ -10,7 +10,9 @@
 namespace Gedmo\Sluggable;
 
 use Doctrine\Common\EventArgs;
+use Doctrine\Persistence\Event\LifecycleEventArgs;
 use Doctrine\Persistence\Event\LoadClassMetadataEventArgs;
+use Doctrine\Persistence\Event\ManagerEventArgs;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\ObjectManager;
 use Gedmo\Exception\InvalidArgumentException;
@@ -239,6 +241,10 @@ public function loadClassMetadata(EventArgs $eventArgs)
     /**
      * Allows identifier fields to be slugged as usual
      *
+     * @param LifecycleEventArgs $args
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function prePersist(EventArgs $args)
@@ -261,6 +267,10 @@ public function prePersist(EventArgs $args)
      * Generate slug on objects being updated during flush
      * if they require changing
      *
+     * @param ManagerEventArgs $args
+     *
+     * @phpstan-param ManagerEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function onFlush(EventArgs $args)

src/SoftDeleteable/SoftDeleteableListener.php

@@ -15,6 +15,7 @@
 use Doctrine\ODM\MongoDB\UnitOfWork as MongoDBUnitOfWork;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\Persistence\Event\LoadClassMetadataEventArgs;
+use Doctrine\Persistence\Event\ManagerEventArgs;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\ObjectManager;
 use Gedmo\Mapping\MappedEventSubscriber;
@@ -60,6 +61,10 @@ public function getSubscribedEvents()
      * If it's a SoftDeleteable object, update the "deletedAt" field
      * and skip the removal of the object
      *
+     * @param ManagerEventArgs $args
+     *
+     * @phpstan-param ManagerEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function onFlush(EventArgs $args)

src/Sortable/SortableListener.php

@@ -12,7 +12,9 @@
 use Doctrine\Common\Comparable;
 use Doctrine\Common\EventArgs;
 use Doctrine\Common\Util\ClassUtils;
+use Doctrine\Persistence\Event\LifecycleEventArgs;
 use Doctrine\Persistence\Event\LoadClassMetadataEventArgs;
+use Doctrine\Persistence\Event\ManagerEventArgs;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\ObjectManager;
 use Gedmo\Mapping\MappedEventSubscriber;
@@ -107,6 +109,10 @@ public function loadClassMetadata(EventArgs $args)
      * The synchronization of the objects in memory is done in postFlush. This
      * ensures that the positions have been successfully persisted to database.
      *
+     * @param ManagerEventArgs $args
+     *
+     * @phpstan-param ManagerEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function onFlush(EventArgs $args)
@@ -151,6 +157,10 @@ public function onFlush(EventArgs $args)
     /**
      * Update maxPositions as needed
      *
+     * @param LifecycleEventArgs $args
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function prePersist(EventArgs $args)
@@ -175,6 +185,10 @@ public function prePersist(EventArgs $args)
     }
 
     /**
+     * @param LifecycleEventArgs $args
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function postPersist(EventArgs $args)
@@ -185,6 +199,10 @@ public function postPersist(EventArgs $args)
     }
 
     /**
+     * @param LifecycleEventArgs $args
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function preUpdate(EventArgs $args)
@@ -195,6 +213,10 @@ public function preUpdate(EventArgs $args)
     }
 
     /**
+     * @param LifecycleEventArgs $args
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function postRemove(EventArgs $args)
@@ -207,6 +229,10 @@ public function postRemove(EventArgs $args)
     /**
      * Sync objects in memory
      *
+     * @param ManagerEventArgs $args
+     *
+     * @phpstan-param ManagerEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function postFlush(EventArgs $args)

src/Translatable/TranslatableListener.php

@@ -12,7 +12,9 @@
 use Doctrine\Common\EventArgs;
 use Doctrine\ODM\MongoDB\DocumentManager;
 use Doctrine\ORM\ORMInvalidArgumentException;
+use Doctrine\Persistence\Event\LifecycleEventArgs;
 use Doctrine\Persistence\Event\LoadClassMetadataEventArgs;
+use Doctrine\Persistence\Event\ManagerEventArgs;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\ObjectManager;
 use Gedmo\Exception\InvalidArgumentException;
@@ -372,6 +374,10 @@ public function getTranslatableLocale($object, $meta, $om = null)
      * This has to be done in the preFlush because, when an entity has been loaded
      * in a different locale, no changes will be detected.
      *
+     * @param ManagerEventArgs $args
+     *
+     * @phpstan-param ManagerEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function preFlush(EventArgs $args)
@@ -409,6 +415,10 @@ public function preFlush(EventArgs $args)
      * Looks for translatable objects being inserted or updated
      * for further processing
      *
+     * @param ManagerEventArgs $args
+     *
+     * @phpstan-param ManagerEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function onFlush(EventArgs $args)
@@ -449,6 +459,10 @@ public function onFlush(EventArgs $args)
      * Checks for inserted object to update their translation
      * foreign keys
      *
+     * @param LifecycleEventArgs $args
+     *
+     * @phpstan-param LifecycleEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function postPersist(EventArgs $args)
@@ -482,6 +496,10 @@ public function postPersist(EventArgs $args)
      * After object is loaded, listener updates the translations
      * by currently used locale
      *
+     * @param ManagerEventArgs $args
+     *
+     * @phpstan-param ManagerEventArgs<ObjectManager> $args
+     *
      * @return void
      */
     public function postLoad(EventArgs $args)