Introduce the Revisionable extension

Author: mbabker

phpstan-baseline.neon

@@ -286,19 +286,44 @@ parameters:
 			path: src/References/ReferencesListener.php
 
 		-
-			message: "#^Call to an undefined method Gedmo\\\\Mapping\\\\Event\\\\AdapterInterface\\:\\:extractIdentifier\\(\\)\\.$#"
-			count: 2
-			path: src/References/ReferencesListener.php
+			message: "#^Method Gedmo\\\\Revisionable\\\\Document\\\\Revision\\:\\:createRevision\\(\\) should return Gedmo\\\\Revisionable\\\\Document\\\\Revision\\<T of object\\> but returns Gedmo\\\\Revisionable\\\\Document\\\\Revision\\<object\\>\\.$#"
+			count: 1
+			path: src/Revisionable/Document/Revision.php
 
 		-
-			message: "#^Call to an undefined method Gedmo\\\\Mapping\\\\Event\\\\AdapterInterface\\:\\:getIdentifier\\(\\)\\.$#"
+			message: "#^Unable to resolve the template type T in call to method Doctrine\\\\ORM\\\\EntityManagerInterface\\:\\:getReference\\(\\)$#"
 			count: 1
-			path: src/References/ReferencesListener.php
+			path: src/Revisionable/Entity/Repository/RevisionRepository.php
 
 		-
-			message: "#^Call to an undefined method Gedmo\\\\Mapping\\\\Event\\\\AdapterInterface\\:\\:getSingleReference\\(\\)\\.$#"
+			message: "#^Method Gedmo\\\\Revisionable\\\\Entity\\\\Revision\\:\\:createRevision\\(\\) should return Gedmo\\\\Revisionable\\\\Entity\\\\Revision\\<T of object\\> but returns Gedmo\\\\Revisionable\\\\Entity\\\\Revision\\<object\\>\\.$#"
 			count: 1
-			path: src/References/ReferencesListener.php
+			path: src/Revisionable/Entity/Revision.php
+
+		-
+			message: "#^Access to an undefined property Doctrine\\\\Persistence\\\\Mapping\\\\ClassMetadata\\:\\:\\$associationMappings\\.$#"
+			count: 1
+			path: src/Revisionable/Mapping/Driver/Xml.php
+
+		-
+			message: "#^Call to an undefined method Doctrine\\\\Persistence\\\\Mapping\\\\ClassMetadata\\<Gedmo\\\\Revisionable\\\\RevisionInterface\\<T of object\\>\\>\\:\\:getReflectionProperty\\(\\)\\.$#"
+			count: 1
+			path: src/Revisionable/RevisionableListener.php
+
+		-
+			message: "#^Call to an undefined method Doctrine\\\\Persistence\\\\ObjectManager\\:\\:getUnitOfWork\\(\\)\\.$#"
+			count: 4
+			path: src/Revisionable/RevisionableListener.php
+
+		-
+			message: "#^Method Gedmo\\\\Revisionable\\\\RevisionableListener\\:\\:getRevisionClass\\(\\) should return class\\-string\\<Gedmo\\\\Revisionable\\\\RevisionInterface\\<T of object\\>\\> but returns class\\-string\\<Gedmo\\\\Revisionable\\\\RevisionInterface\\<object\\>\\>\\.$#"
+			count: 1
+			path: src/Revisionable/RevisionableListener.php
+
+		-
+			message: "#^Method Gedmo\\\\Tool\\\\WrapperInterface\\<Doctrine\\\\Persistence\\\\Mapping\\\\ClassMetadata\\>\\:\\:getIdentifier\\(\\) invoked with 2 parameters, 0\\-1 required\\.$#"
+			count: 2
+			path: src/Revisionable/RevisionableListener.php
 
 		-
 			message: "#^Call to an undefined method Doctrine\\\\Persistence\\\\Mapping\\\\ClassMetadata\\<object\\>\\:\\:getReflectionProperty\\(\\)\\.$#"
@@ -400,11 +425,6 @@ parameters:
 			count: 1
 			path: src/SoftDeleteable/Query/TreeWalker/SoftDeleteableWalker.php
 
-		-
-			message: "#^Call to an undefined method Gedmo\\\\Mapping\\\\Event\\\\AdapterInterface\\:\\:getDateValue\\(\\)\\.$#"
-			count: 1
-			path: src/SoftDeleteable/SoftDeleteableListener.php
-
 		-
 			message: "#^Access to offset 'inherited' on an unknown class Doctrine\\\\ODM\\\\MongoDB\\\\Mapping\\\\AssociationFieldMapping\\.$#"
 			count: 1
@@ -465,26 +485,11 @@ parameters:
 			count: 1
 			path: src/Timestampable/Mapping/Driver/Yaml.php
 
-		-
-			message: "#^Call to an undefined method Doctrine\\\\Persistence\\\\ObjectManager\\:\\:getUnitOfWork\\(\\)\\.$#"
-			count: 1
-			path: src/Tool/Wrapper/EntityWrapper.php
-
-		-
-			message: "#^Parameter \\#2 \\$em of class Gedmo\\\\Tool\\\\Wrapper\\\\EntityWrapper constructor expects Doctrine\\\\ORM\\\\EntityManagerInterface, Doctrine\\\\Persistence\\\\ObjectManager given\\.$#"
-			count: 1
-			path: src/Tool/Wrapper/EntityWrapper.php
-
 		-
 			message: "#^Access to an undefined property ProxyManager\\\\Proxy\\\\GhostObjectInterface\\:\\:\\$identifier\\.$#"
 			count: 1
 			path: src/Tool/Wrapper/MongoDocumentWrapper.php
 
-		-
-			message: "#^Call to an undefined method Doctrine\\\\Persistence\\\\ObjectManager\\:\\:getUnitOfWork\\(\\)\\.$#"
-			count: 2
-			path: src/Tool/Wrapper/MongoDocumentWrapper.php
-
 		-
 			message: "#^Call to function property_exists\\(\\) with \\$this\\(Gedmo\\\\Translatable\\\\Hydrator\\\\ORM\\\\ObjectHydrator\\) and '_em' will always evaluate to false\\.$#"
 			count: 1
@@ -865,6 +870,36 @@ parameters:
 			count: 1
 			path: tests/Gedmo/Mapping/Xml/TranslatableMappingTest.php
 
+		-
+			message: "#^Method Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Document\\\\CommentRevision\\:\\:createRevision\\(\\) should return Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Document\\\\CommentRevision\\<T of Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Document\\\\Comment\\> but returns Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Document\\\\CommentRevision\\<Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Document\\\\Comment\\>\\.$#"
+			count: 1
+			path: tests/Gedmo/Revisionable/Fixture/Document/CommentRevision.php
+
+		-
+			message: "#^Method Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\CommentRevision\\:\\:createRevision\\(\\) should return Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\CommentRevision\\<T of Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\Comment\\> but returns Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\CommentRevision\\<Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\Comment\\>\\.$#"
+			count: 1
+			path: tests/Gedmo/Revisionable/Fixture/Entity/CommentRevision.php
+
+		-
+			message: "#^Call to an undefined method Doctrine\\\\ORM\\\\EntityRepository\\<Gedmo\\\\Revisionable\\\\Document\\\\Revision\\>\\:\\:getRevisions\\(\\)\\.$#"
+			count: 1
+			path: tests/Gedmo/Revisionable/RevisionableDocumentTest.php
+
+		-
+			message: "#^Parameter \\#1 \\$entity of method Gedmo\\\\Revisionable\\\\Entity\\\\Repository\\\\RevisionRepository\\<Gedmo\\\\Revisionable\\\\Entity\\\\Revision\\>\\:\\:getRevisions\\(\\) expects Gedmo\\\\Revisionable\\\\Entity\\\\Revision, Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\Address given\\.$#"
+			count: 1
+			path: tests/Gedmo/Revisionable/RevisionableEntityTest.php
+
+		-
+			message: "#^Parameter \\#1 \\$entity of method Gedmo\\\\Revisionable\\\\Entity\\\\Repository\\\\RevisionRepository\\<Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\CommentRevision\\>\\:\\:getRevisions\\(\\) expects Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\CommentRevision, Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\Comment given\\.$#"
+			count: 1
+			path: tests/Gedmo/Revisionable/RevisionableEntityTest.php
+
+		-
+			message: "#^Parameter \\#1 \\$entity of method Gedmo\\\\Revisionable\\\\Entity\\\\Repository\\\\RevisionRepository\\<Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\CommentRevision\\>\\:\\:revert\\(\\) expects Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\CommentRevision, Gedmo\\\\Tests\\\\Revisionable\\\\Fixture\\\\Entity\\\\Comment given\\.$#"
+			count: 1
+			path: tests/Gedmo/Revisionable/RevisionableEntityTest.php
+
 		-
 			message: "#^Method Gedmo\\\\Tests\\\\Sluggable\\\\Fixture\\\\Doctrine\\\\FakeFilter\\:\\:addFilterConstraint\\(\\) has parameter \\$targetTableAlias with no type specified\\.$#"
 			count: 1

phpunit.xml.dist

@@ -9,7 +9,7 @@
     processIsolation="false"
     stopOnFailure="false"
     bootstrap="./tests/bootstrap.php"
-    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
+    xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
 >
     <coverage>
         <include>
@@ -44,6 +44,9 @@
         <testsuite name="Loggable Extension">
             <directory suffix="Test.php">./tests/Gedmo/Loggable/</directory>
         </testsuite>
+        <testsuite name="Revisionable Extension">
+            <directory suffix="Test.php">./tests/Gedmo/Revisionable/</directory>
+        </testsuite>
         <testsuite name="Sortable Extension">
             <directory suffix="Test.php">./tests/Gedmo/Sortable/</directory>
         </testsuite>

schemas/orm/doctrine-extensions-mapping-2-2.xsd

@@ -27,6 +27,7 @@
   <xs:element name="tree-closure" type="gedmo:tree-closure"/>
   <xs:element name="tree-path" type="gedmo:tree-path"/>
   <xs:element name="loggable" type="gedmo:loggable"/>
+  <xs:element name="revisionable" type="gedmo:revisionable"/>
   <xs:element name="soft-deleteable" type="gedmo:soft-deleteable"/>
   <xs:element name="uploadable" type="gedmo:uploadable"/>
   <xs:element name="reference" type="gedmo:reference"/>
@@ -92,6 +93,10 @@
     <xs:attribute name="log-entry-class" type="xs:string" use="optional" />
   </xs:complexType>
 
+  <xs:complexType name="revisionable">
+    <xs:attribute name="revision-class" type="xs:string" use="optional" />
+  </xs:complexType>
+
   <xs:complexType name="slug">
     <xs:sequence>
       <xs:element name="handler" type="gedmo:handler" minOccurs="0" maxOccurs="unbounded"/>

src/AbstractTrackingListener.php

@@ -28,6 +28,11 @@
  * The AbstractTrackingListener provides generic functions for all listeners.
  *
  * @author Gediminas Morkevicius <[email protected]>
+ *
+ * @template TConfig of array
+ * @template TEventAdapter of AdapterInterface
+ *
+ * @extends MappedEventSubscriber<TConfig, TEventAdapter>
  */
 abstract class AbstractTrackingListener extends MappedEventSubscriber
 {

src/Blameable/BlameableListener.php

@@ -11,6 +11,7 @@
 
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Gedmo\AbstractTrackingListener;
+use Gedmo\Blameable\Mapping\Event\BlameableAdapter;
 use Gedmo\Exception\InvalidArgumentException;
 
 /**
@@ -19,6 +20,8 @@
  *
  * @author Gediminas Morkevicius <[email protected]>
  *
+ * @extends AbstractTrackingListener<array, BlameableAdapter>
+ *
  * @final since gedmo/doctrine-extensions 3.11
  */
 class BlameableListener extends AbstractTrackingListener

src/DoctrineExtensions.php

@@ -41,6 +41,7 @@ public static function registerMappingIntoDriverChainORM(MappingDriverChain $dri
         $paths = [
             __DIR__.'/Translatable/Entity',
             __DIR__.'/Loggable/Entity',
+            __DIR__.'/Revisionable/Entity',
             __DIR__.'/Tree/Entity',
         ];
 
@@ -62,6 +63,7 @@ public static function registerAbstractMappingIntoDriverChainORM(MappingDriverCh
         $paths = [
             __DIR__.'/Translatable/Entity/MappedSuperclass',
             __DIR__.'/Loggable/Entity/MappedSuperclass',
+            __DIR__.'/Revisionable/Entity/MappedSuperclass',
             __DIR__.'/Tree/Entity/MappedSuperclass',
         ];
 
@@ -83,6 +85,7 @@ public static function registerMappingIntoDriverChainMongodbODM(MappingDriverCha
         $paths = [
             __DIR__.'/Translatable/Document',
             __DIR__.'/Loggable/Document',
+            __DIR__.'/Revisionable/Document',
         ];
 
         if (\PHP_VERSION_ID >= 80000) {
@@ -103,6 +106,7 @@ public static function registerAbstractMappingIntoDriverChainMongodbODM(MappingD
         $paths = [
             __DIR__.'/Translatable/Document/MappedSuperclass',
             __DIR__.'/Loggable/Document/MappedSuperclass',
+            __DIR__.'/Revisionable/Document/MappedSuperclass',
         ];
 
         if (\PHP_VERSION_ID >= 80000) {

src/IpTraceable/IpTraceableListener.php

@@ -12,6 +12,7 @@
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Gedmo\AbstractTrackingListener;
 use Gedmo\Exception\InvalidArgumentException;
+use Gedmo\IpTraceable\Mapping\Event\IpTraceableAdapter;
 use Gedmo\Mapping\Event\AdapterInterface;
 
 /**
@@ -20,6 +21,8 @@
  *
  * @author Pierre-Charles Bertineau <[email protected]>
  *
+ * @extends AbstractTrackingListener<array, IpTraceableAdapter>
+ *
  * @final since gedmo/doctrine-extensions 3.11
  */
 class IpTraceableListener extends AbstractTrackingListener

src/Loggable/LoggableListener.php

@@ -35,11 +35,9 @@
  *   versioned?: string[],
  * }
  *
- * @phpstan-method LoggableConfiguration getConfiguration(ObjectManager $objectManager, $class)
+ * @template T of Loggable|object
  *
- * @method LoggableAdapter getEventAdapter(EventArgs $args)
- *
- * @phpstan-template T of Loggable|object
+ * @phpstan-extends MappedEventSubscriber<LoggableConfiguration, LoggableAdapter>
  */
 class LoggableListener extends MappedEventSubscriber
 {

src/Mapping/Annotation/Revisionable.php

@@ -0,0 +1,64 @@
+<?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\Mapping\Annotation;
+
+use Doctrine\Common\Annotations\Annotation;
+use Doctrine\Deprecations\Deprecation;
+use Gedmo\Mapping\Annotation\Annotation as GedmoAnnotation;
+use Gedmo\Revisionable\RevisionInterface;
+
+/**
+ * Revisionable annotation for the revisionable behavioral extension
+ *
+ * @phpstan-template T of RevisionInterface
+ *
+ * @Annotation
+ *
+ * @NamedArgumentConstructor
+ *
+ * @Target("CLASS")
+ *
+ * @author Gediminas Morkevicius <[email protected]>
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final class Revisionable implements GedmoAnnotation
+{
+    use ForwardCompatibilityTrait;
+
+    /**
+     * @phpstan-var class-string<T>|null
+     */
+    public ?string $revisionClass;
+
+    /**
+     * @param array<string, mixed> $data
+     *
+     * @phpstan-param class-string<T>|null $revisionClass
+     */
+    public function __construct(array $data = [], ?string $revisionClass = null)
+    {
+        if ([] !== $data) {
+            Deprecation::trigger(
+                'gedmo/doctrine-extensions',
+                'https://github.com/doctrine-extensions/DoctrineExtensions/pull/2357',
+                'Passing an array as first argument to "%s()" is deprecated. Use named arguments instead.',
+                __METHOD__
+            );
+
+            $args = func_get_args();
+
+            $this->revisionClass = $this->getAttributeValue($data, 'revisionClass', $args, 1, $revisionClass);
+
+            return;
+        }
+
+        $this->revisionClass = $revisionClass;
+    }
+}

src/Mapping/Annotation/Versioned.php

@@ -13,7 +13,7 @@
 use Gedmo\Mapping\Annotation\Annotation as GedmoAnnotation;
 
 /**
- * Versioned annotation for Loggable behavioral extension
+ * Versioned annotation for use with the Loggable and Revisionable extensions
  *
  * @Annotation
  *