[Loggable] Add LogEntryInterface

Author: phansys

CHANGELOG.md

@@ -23,6 +23,7 @@ a release.
 - Tree: Add `Nested::ALLOWED_NODE_POSITIONS` constant in order to expose the available node positions
 - Support for `doctrine/collections` 2.0
 - Support for `doctrine/event-manager` 2.0
+- Loggable: Add `LogEntryInterface` interface in order to be implemented by log entry models
 
 ### Fixed
 - Sortable: Fix return value check of Comparable interface (#2541)
@@ -35,6 +36,9 @@ a release.
 - Deprecate the annotation reader being allowed to be any object.
   In 4.0, a `Doctrine\Common\Annotations\Reader` or `Gedmo\Mapping\Driver\AttributeReader` instance will be required.
 - `Gedmo\DoctrineExtensions::registerAnnotations()` is deprecated and will be removed in 4.0, the method has been no-op'd as all supported `doctrine/annotations` versions support autoloading
+- Loggable: Constants `LoggableListener::ACTION_CREATE`, `LoggableListener::ACTION_UPDATE` and `LoggableListener::ACTION_REMOVE`
+  are deprecated. Use `LogEntryInterface::ACTION_CREATE`, `LogEntryInterface::ACTION_UPDATE` and `LogEntryInterface::ACTION_REMOVE`
+  instead.
 
 ## [3.10.0] - 2022-11-14
 ### Changed

doc/loggable.md

@@ -32,16 +32,16 @@ on how to setup and use the extensions in most optimized way.
 
 ### Loggable annotations:
 
-- **@Gedmo\Mapping\Annotation\Loggable(logEntryClass="my\class")** this class annotation
-will store logs to optionally specified **logEntryClass**. You will still need to specify versioned fields with the following annotation.
+- **@Gedmo\Mapping\Annotation\Loggable(logEntryClass="My\LoggableModel")** this class annotation will store logs to optionally
+  specified **logEntryClass**. The class provided in this annotation MUST implement ``Gedmo\Loggable\LogEntryInterface``. You will
+  still need to specify versioned fields with the following annotation.
 - **@Gedmo\Mapping\Annotation\Versioned** tracks annotated property for changes
 
-**Note:** If you need to use a different class, it must extend ``Gedmo\Loggable\Entity\MappedSuperclass\AbstractLogEntry``.
-
 ### Loggable attributes:
 
-- **\#[Gedmo\Mapping\Annotation\Loggable(logEntryClass: MyClass::class]** this class attribute
-will store logs to optionally specified **logEntryClass**. You will still need to specify versioned fields with the following attribute.
+- **\#[Gedmo\Mapping\Annotation\Loggable(logEntryClass: My\LoggableModel::class]** this class attribute will store logs to optionally
+  specified **logEntryClass**. The class provided in this attribute MUST implement ``Gedmo\Loggable\LogEntryInterface``. You will
+  still need to specify versioned fields with the following attribute.
 - **\#[Gedmo\Mapping\Annotation\Versioned]** tracks attributed property for changes
 
 ### Loggable username:

phpstan-baseline.neon

@@ -76,12 +76,12 @@ parameters:
 			path: src/Loggable/Document/Repository/LogEntryRepository.php
 
 		-
-			message: "#^Call to an undefined method Doctrine\\\\Persistence\\\\Mapping\\\\ClassMetadata\\<object\\>\\:\\:getReflectionProperty\\(\\)\\.$#"
+			message: "#^Call to an undefined method Doctrine\\\\Persistence\\\\Mapping\\\\ClassMetadata\\<Gedmo\\\\Loggable\\\\LogEntryInterface\\>\\:\\:getReflectionProperty\\(\\)\\.$#"
 			count: 1
 			path: src/Loggable/LoggableListener.php
 
 		-
-			message: "#^Call to an undefined method Doctrine\\\\Persistence\\\\Mapping\\\\ClassMetadata\\<object\\>\\:\\:newInstance\\(\\)\\.$#"
+			message: "#^Call to an undefined method Doctrine\\\\Persistence\\\\Mapping\\\\ClassMetadata\\<Gedmo\\\\Loggable\\\\LogEntryInterface\\>\\:\\:newInstance\\(\\)\\.$#"
 			count: 1
 			path: src/Loggable/LoggableListener.php
 

src/Loggable/Document/MappedSuperclass/AbstractLogEntry.php

@@ -11,12 +11,17 @@
 
 use Doctrine\ODM\MongoDB\Mapping\Annotations as MongoODM;
 use Doctrine\ODM\MongoDB\Types\Type;
+use Gedmo\Loggable\LogEntryInterface;
 
 /**
+ * @phpstan-template T of object
+ *
+ * @phpstan-implements LogEntryInterface<T>
+ *
  * @MongoODM\MappedSuperclass
  */
 #[MongoODM\MappedSuperclass]
-abstract class AbstractLogEntry
+abstract class AbstractLogEntry implements LogEntryInterface
 {
     /**
      * @var string|null
@@ -29,6 +34,8 @@ abstract class AbstractLogEntry
     /**
      * @var string|null
      *
+     * @phpstan-var self::ACTION_CREATE|self::ACTION_UPDATE|self::ACTION_REMOVE|null
+     *
      * @MongoODM\Field(type="string")
      */
     #[MongoODM\Field(type: Type::STRING)]
@@ -53,6 +60,8 @@ abstract class AbstractLogEntry
     /**
      * @var string|null
      *
+     * @phpstan-var class-string<T>|null
+     *
      * @MongoODM\Field(type="string")
      */
     #[MongoODM\Field(type: Type::STRING)]

src/Loggable/Entity/MappedSuperclass/AbstractLogEntry.php

@@ -11,12 +11,17 @@
 
 use Doctrine\DBAL\Types\Types;
 use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Loggable\LogEntryInterface;
 
 /**
+ * @phpstan-template T of object
+ *
+ * @phpstan-implements LogEntryInterface<T>
+ *
  * @ORM\MappedSuperclass
  */
 #[ORM\MappedSuperclass]
-abstract class AbstractLogEntry
+abstract class AbstractLogEntry implements LogEntryInterface
 {
     /**
      * @var int|null
@@ -33,6 +38,8 @@ abstract class AbstractLogEntry
     /**
      * @var string|null
      *
+     * @phpstan-var self::ACTION_CREATE|self::ACTION_UPDATE|self::ACTION_REMOVE|null
+     *
      * @ORM\Column(type="string", length=8)
      */
     #[ORM\Column(type: Types::STRING, length: 8)]
@@ -57,6 +64,8 @@ abstract class AbstractLogEntry
     /**
      * @var string|null
      *
+     * @phpstan-var class-string<T>|null
+     *
      * @ORM\Column(name="object_class", type="string", length=191)
      */
     #[ORM\Column(name: 'object_class', type: Types::STRING, length: 191)]

src/Loggable/LogEntryInterface.php

@@ -0,0 +1,106 @@
+<?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\Loggable;
+
+/**
+ * Interface to be implemented by log entry models.
+ *
+ * @phpstan-template T of object
+ *
+ * @author Javier Spagnoletti <[email protected]>
+ */
+interface LogEntryInterface
+{
+    public const ACTION_CREATE = 'create';
+
+    public const ACTION_UPDATE = 'update';
+
+    public const ACTION_REMOVE = 'remove';
+
+    /**
+     * @phpstan-param self::ACTION_CREATE|self::ACTION_UPDATE|self::ACTION_REMOVE $action
+     *
+     * @return void
+     */
+    public function setAction(string $action);
+
+    /**
+     * @return string|null
+     *
+     * @phpstan-return self::ACTION_CREATE|self::ACTION_UPDATE|self::ACTION_REMOVE|null
+     */
+    public function getAction();
+
+    /**
+     * @return void
+     */
+    public function setUsername(string $username);
+
+    /**
+     * @return string|null
+     */
+    public function getUsername();
+
+    /**
+     * @phpstan-param class-string<T> $objectClass
+     *
+     * @return void
+     */
+    public function setObjectClass(string $objectClass);
+
+    /**
+     * @return string|null
+     *
+     * @phpstan-return class-string<T>
+     */
+    public function getObjectClass();
+
+    /**
+     * @return void
+     */
+    public function setLoggedAt();
+
+    /**
+     * @return \DateTimeInterface|null
+     */
+    public function getLoggedAt();
+
+    /**
+     * @return void
+     */
+    public function setObjectId(string $objectId);
+
+    /**
+     * @return string|null
+     */
+    public function getObjectId();
+
+    /**
+     * @param array<string, mixed> $data
+     *
+     * @return void
+     */
+    public function setData(array $data);
+
+    /**
+     * @return array<string, mixed>|null
+     */
+    public function getData();
+
+    /**
+     * @return void
+     */
+    public function setVersion(int $version);
+
+    /**
+     * @return int|null
+     */
+    public function getVersion();
+}

src/Loggable/LoggableListener.php

@@ -24,7 +24,7 @@
  *
  * @phpstan-type LoggableConfiguration = array{
  *   loggable?: bool,
- *   logEntryClass?: class-string,
+ *   logEntryClass?: class-string<LogEntryInterface>,
  *   useObjectClass?: class-string,
  *   versioned?: string[],
  * }
@@ -38,19 +38,19 @@
 class LoggableListener extends MappedEventSubscriber
 {
     /**
-     * Create action
+     * @deprecated use `LogEntryInterface::ACTION_CREATE` instead
      */
-    public const ACTION_CREATE = 'create';
+    public const ACTION_CREATE = LogEntryInterface::ACTION_CREATE;
 
     /**
-     * Update action
+     * @deprecated use `LogEntryInterface::ACTION_UPDATE` instead
      */
-    public const ACTION_UPDATE = 'update';
+    public const ACTION_UPDATE = LogEntryInterface::ACTION_UPDATE;
 
     /**
-     * Remove action
+     * @deprecated use `LogEntryInterface::ACTION_REMOVE` instead
      */
-    public const ACTION_REMOVE = 'remove';
+    public const ACTION_REMOVE = LogEntryInterface::ACTION_REMOVE;
 
     /**
      * Username for identification
@@ -64,7 +64,7 @@ class LoggableListener extends MappedEventSubscriber
      * key generated yet - MySQL case. These entries
      * will be updated with new keys on postPersist event
      *
-     * @var array
+     * @var array<int, LogEntryInterface>
      */
     protected $pendingLogEntryInserts = [];
 
@@ -74,7 +74,9 @@ class LoggableListener extends MappedEventSubscriber
      * These are pending relations in case it does not
      * have an identifier yet
      *
-     * @var array
+     * @var array<int, array<int, array<string, LogEntryInterface|string>>>
+     *
+     * @phpstan-var array<int, array<int, array{log: LogEntryInterface, field: string}>>
      */
     protected $pendingRelatedObjects = [];
 
@@ -186,13 +188,13 @@ public function onFlush(EventArgs $eventArgs)
         $uow = $om->getUnitOfWork();
 
         foreach ($ea->getScheduledObjectInsertions($uow) as $object) {
-            $this->createLogEntry(self::ACTION_CREATE, $object, $ea);
+            $this->createLogEntry(LogEntryInterface::ACTION_CREATE, $object, $ea);
         }
         foreach ($ea->getScheduledObjectUpdates($uow) as $object) {
-            $this->createLogEntry(self::ACTION_UPDATE, $object, $ea);
+            $this->createLogEntry(LogEntryInterface::ACTION_UPDATE, $object, $ea);
         }
         foreach ($ea->getScheduledObjectDeletions($uow) as $object) {
-            $this->createLogEntry(self::ACTION_REMOVE, $object, $ea);
+            $this->createLogEntry(LogEntryInterface::ACTION_REMOVE, $object, $ea);
         }
     }
 
@@ -203,7 +205,7 @@ public function onFlush(EventArgs $eventArgs)
      * @phpstan-param class-string $class
      *
      * @return string
-     * @phpstan-return class-string
+     * @phpstan-return class-string<LogEntryInterface>
      */
     protected function getLogEntryClass(LoggableAdapter $ea, $class)
     {
@@ -214,8 +216,8 @@ protected function getLogEntryClass(LoggableAdapter $ea, $class)
      * Handle any custom LogEntry functionality that needs to be performed
      * before persisting it
      *
-     * @param object $logEntry The LogEntry being persisted
-     * @param object $object   The object being Logged
+     * @param LogEntryInterface $logEntry The LogEntry being persisted
+     * @param object            $object   The object being Logged
      *
      * @return void
      */
@@ -231,9 +233,9 @@ protected function getNamespace()
     /**
      * Returns an objects changeset data
      *
-     * @param LoggableAdapter $ea
-     * @param object          $object
-     * @param object          $logEntry
+     * @param LoggableAdapter   $ea
+     * @param object            $object
+     * @param LogEntryInterface $logEntry
      *
      * @return array
      */
@@ -278,7 +280,9 @@ protected function getObjectChangeSetData($ea, $object, $logEntry)
      * @param string $action
      * @param object $object
      *
-     * @return \Gedmo\Loggable\Entity\MappedSuperclass\AbstractLogEntry|null
+     * @phpstan-param LogEntryInterface::ACTION_CREATE|LogEntryInterface::ACTION_UPDATE|LogEntryInterface::ACTION_REMOVE $action
+     *
+     * @return LogEntryInterface|null
      */
     protected function createLogEntry($action, $object, LoggableAdapter $ea)
     {
@@ -294,7 +298,7 @@ protected function createLogEntry($action, $object, LoggableAdapter $ea)
         if ($config = $this->getConfiguration($om, $meta->getName())) {
             $logEntryClass = $this->getLogEntryClass($ea, $meta->getName());
             $logEntryMeta = $om->getClassMetadata($logEntryClass);
-            /** @var \Gedmo\Loggable\Entity\LogEntry $logEntry */
+            /** @var LogEntryInterface $logEntry */
             $logEntry = $logEntryMeta->newInstance();
 
             $logEntry->setAction($action);
@@ -304,23 +308,23 @@ protected function createLogEntry($action, $object, LoggableAdapter $ea)
 
             // check for the availability of the primary key
             $uow = $om->getUnitOfWork();
-            if (self::ACTION_CREATE === $action && $ea->isPostInsertGenerator($meta)) {
+            if (LogEntryInterface::ACTION_CREATE === $action && $ea->isPostInsertGenerator($meta)) {
                 $this->pendingLogEntryInserts[spl_object_id($object)] = $logEntry;
             } else {
                 $logEntry->setObjectId($wrapped->getIdentifier());
             }
             $newValues = [];
-            if (self::ACTION_REMOVE !== $action && isset($config['versioned'])) {
+            if (LogEntryInterface::ACTION_REMOVE !== $action && isset($config['versioned'])) {
                 $newValues = $this->getObjectChangeSetData($ea, $object, $logEntry);
                 $logEntry->setData($newValues);
             }
 
-            if (self::ACTION_UPDATE === $action && 0 === count($newValues)) {
+            if (LogEntryInterface::ACTION_UPDATE === $action && 0 === count($newValues)) {
                 return null;
             }
 
             $version = 1;
-            if (self::ACTION_CREATE !== $action) {
+            if (LogEntryInterface::ACTION_CREATE !== $action) {
                 $version = $ea->getNewVersion($logEntryMeta, $object);
                 if (empty($version)) {
                     // was versioned later