Introduce the Revisionable extension

CHANGELOG.md

@@ -42,6 +42,7 @@ a release.
 - SoftDeleteable: Resolved a bug where a soft-deleted object isn't remove from the ObjectManager (#2930)
 
 ### Added
+- Introduced the `Revisionable` extension as a modern replacement to the `Loggable` extension (#2825)
 - IP address provider for use with extensions with IP address references (#2928)
 
 ## [3.19.0] - 2025-02-24

composer.json

@@ -10,6 +10,7 @@
         "gedmo",
         "sluggable",
         "loggable",
+        "revisionable",
         "odm",
         "orm",
         "translatable",

doc/annotations.md

@@ -14,6 +14,7 @@ extension, refer to the extension's documentation page.
 - [Loggable Extension](#loggable-extension)
 - [Reference Integrity Extension](#reference-integrity-extension)
 - [References Extension](#references-extension)
+- [Revisionable Extension](#revisionable-extension)
 - [Sluggable Extension](#sluggable-extension)
 - [Soft Deleteable Extension](#soft-deleteable-extension)
 - [Sortable Extension](#sortable-extension)
@@ -495,6 +496,79 @@ class Article
 }
 ```
 
+### Revisionable Extension
+
+The below annotations are used to configure the [Revisionable extension](./revisionable.md).
+
+#### `@Gedmo\Mapping\Annotation\Revisionable`
+
+The `Revisionable` annotation is a class annotation used to identify objects which can have changes logged,
+all revisionable objects **MUST** have this annotation.
+
+Required Attributes:
+
+- **revisionClass** - A custom model class implementing `Gedmo\Revisionable\RevisionInterface` to use for logging changes;
+  defaults to `Gedmo\Revisionable\Entity\Revision` for Doctrine ORM users or
+  `Gedmo\Revisionable\Document\Revision` for Doctrine MongoDB ODM users
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ORM\Entity
+ * @Gedmo\Revisionable(revisionClass="App\Entity\ArticleRevision")
+ */
+class Article {}
+```
+
+#### `@Gedmo\Mapping\Annotation\KeepRevisions`
+
+The `KeepRevisions` annotation is a property annotation used to identify properties whose changes should be logged.
+This annotation can be set for properties with a single value (i.e. a scalar type or an object such as
+`DateTimeInterface`), but not for collections. Fields with revisions can be restored to an earlier version.
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+/**
+ * @ORM\Entity
+ * @Gedmo\Revisionable
+ */
+class Comment
+{
+    /**
+    * @ORM\Id
+    * @ORM\GeneratedValue
+    * @ORM\Column(type="integer")
+    */
+    public ?int $id = null;
+
+    /**
+     * @ORM\ManyToOne(targetEntity="App\Entity\Article", inversedBy="comments")
+     * @Gedmo\KeepRevisions
+     */
+    public ?Article $article = null;
+
+    /**
+     * @ORM\Column(type="string")
+     * @Gedmo\KeepRevisions
+     */
+    public ?string $body = null;
+}
+```
+
 ### Sluggable Extension
 
 The below annotations are used to configure the [Sluggable extension](./sluggable.md).

doc/attributes.md

@@ -14,6 +14,7 @@ For more detailed usage of each extension, refer to the extension's documentatio
 - [Loggable Extension](#loggable-extension)
 - [Reference Integrity Extension](#reference-integrity-extension)
 - [References Extension](#references-extension)
+- [Revisionable Extension](#revisionable-extension)
 - [Sluggable Extension](#sluggable-extension)
 - [Soft Deleteable Extension](#soft-deleteable-extension)
 - [Sortable Extension](#sortable-extension)
@@ -440,6 +441,70 @@ class Article
 }
 ```
 
+### Revisionable Extension
+
+The below attributes are used to configure the [Revisionable extension](./revisionable.md).
+
+#### `#[Gedmo\Mapping\Annotation\Revisionable]`
+
+The `Revisionable` attribute is a class attribute used to identify objects which can have changes logged,
+all revisionable objects **MUST** have this attribute.
+
+Required Parameters:
+
+- **revisionClass** - A custom model class implementing `Gedmo\Revisionable\RevisionInterface` to use for logging changes;
+  defaults to `Gedmo\Revisionable\Entity\Revision` for Doctrine ORM users or
+  `Gedmo\Revisionable\Document\Revision` for Doctrine MongoDB ODM users
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+#[ORM\Entity]
+#[Gedmo\Revisionable(revisionClass: ArticleRevision::class)]
+class Article {}
+```
+
+#### `#[Gedmo\Mapping\Annotation\KeepRevisions]`
+
+The `KeepRevisions` attribute is a property attribute used to identify properties whose changes should be logged.
+This attribute can be set for properties with a single value (i.e. a scalar type or an object such as
+`DateTimeInterface`), but not for collections. Fields with revisions can be restored to an earlier version.
+
+Example:
+
+```php
+<?php
+namespace App\Entity;
+
+use Doctrine\DBAL\Types\Types;
+use Doctrine\ORM\Mapping as ORM;
+use Gedmo\Mapping\Annotation as Gedmo;
+
+#[ORM\Entity]
+#[Gedmo\Revisionable]
+class Comment
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column(type: Types::INTEGER)]
+    public ?int $id = null;
+
+    #[ORM\ManyToOne(targetEntity: Article::class, inversedBy: 'comments')]
+    #[Gedmo\KeepRevisions]
+    public ?Article $article = null;
+
+    #[ORM\Column(type: Types::STRING)]
+    #[Gedmo\KeepRevisions]
+    public ?string $body = null;
+}
+```
+
 ### Sluggable Extension
 
 The below attributes are used to configure the [Sluggable extension](./sluggable.md).

doc/frameworks/laminas.md

@@ -44,6 +44,7 @@ use Gedmo\Blameable\BlameableListener;
 use Gedmo\IpTraceable\IpTraceableListener;
 use Gedmo\Loggable\LoggableListener;
 use Gedmo\Mapping\Driver\AttributeReader;
+use Gedmo\Revisionable\RevisionableListener;
 use Gedmo\Sluggable\SluggableListener;
 use Gedmo\SoftDeleteable\SoftDeleteableListener;
 use Gedmo\Sortable\SortableListener;
@@ -83,6 +84,14 @@ return [
 
                 return $listener;
             },
+            'gedmo.listener.revisionable' => function (ContainerInterface $container, string $requestedName): RevisionableListener {
+                $listener = new RevisionableListener();
+
+                // This call configures the listener to use the attribute driver service created above; if using annotations, you will need to provide the appropriate service instead
+                $listener->setAnnotationReader($container->get('gedmo.mapping.driver.attribute'));
+
+                return $listener;
+            },
             'gedmo.listener.sluggable' => function (ContainerInterface $container, string $requestedName): SluggableListener {
                 $listener = new SluggableListener();
 
@@ -141,6 +150,7 @@ return [
                     'gedmo.listener.blameable',
                     'gedmo.listener.ip_traceable',
                     'gedmo.listener.loggable',
+                    'gedmo.listener.revisionable',
                     'gedmo.listener.sluggable',
                     'gedmo.listener.soft_deleteable',
                     'gedmo.listener.sortable',
@@ -232,8 +242,8 @@ return [
 
 ## Registering Mapping Configuration
 
-When using the [Loggable](../loggable.md), [Translatable](../translatable.md), or [Tree](../tree.md) extensions, you will
-need to register the mappings for these extensions to your object managers.
+When using the [Loggable](../loggable.md), [Revisionable](../revisionable.md), [Translatable](../translatable.md),
+or [Tree](../tree.md) extensions, you will need to register the mappings for these extensions to your object managers.
 
 > [!NOTE]
 > These extensions only provide mappings through annotations or attributes, with support for annotations being deprecated. If using annotations, you will need to ensure the [`doctrine/annotations`](https://www.doctrine-project.org/projects/annotations.html) library is installed and configured.
@@ -258,6 +268,7 @@ return [
                 'class' => AttributeDriver::class, // If your application is using annotations, use the AnnotationDriver class instead
                 'paths' => [
                     '/path/to/vendor/gedmo/doctrine-extensions/src/Loggable/Document',
+                    '/path/to/vendor/gedmo/doctrine-extensions/src/Revisionable/Document',
                     '/path/to/vendor/gedmo/doctrine-extensions/src/Translatable/Document',
                 ],
             ],
@@ -288,6 +299,7 @@ return [
                 'class' => AttributeDriver::class, // If your application is using annotations, use the AnnotationDriver class instead
                 'paths' => [
                     '/path/to/vendor/gedmo/doctrine-extensions/src/Loggable/Entity',
+                    '/path/to/vendor/gedmo/doctrine-extensions/src/Revisionable/Entity',
                     '/path/to/vendor/gedmo/doctrine-extensions/src/Translatable/Entity',
                     '/path/to/vendor/gedmo/doctrine-extensions/src/Tree/Entity',
                 ],
@@ -310,6 +322,8 @@ $ vendor/bin/doctrine-module orm:info
 
  [OK]   Gedmo\Loggable\Entity\LogEntry
  [OK]   Gedmo\Loggable\Entity\MappedSuperclass\AbstractLogEntry
+ [OK]   Gedmo\Revisionable\Entity\Revision
+ [OK]   Gedmo\Revisionable\Entity\MappedSuperclass\AbstractRevision
  [OK]   Gedmo\Translatable\Entity\Translation
  [OK]   Gedmo\Translatable\Entity\MappedSuperclass\AbstractTranslation
  [OK]   Gedmo\Translatable\Entity\MappedSuperclass\AbstractPersonalTranslation
@@ -374,9 +388,9 @@ return [
 
 ## Configuring Extensions via Event Listeners
 
-When using the [Blameable](../blameable.md), [IP Traceable](../ip_traceable.md), [Loggable](../loggable.md), or
-[Translatable](../translatable.md) extensions, to work correctly, they require extra information that must be set
-at runtime.
+When using the [Blameable](../blameable.md), [IP Traceable](../ip_traceable.md), [Loggable](../loggable.md),
+[Revisionable](../revisionable.md), or [Translatable](../translatable.md) extensions, to work correctly,
+they require extra information that must be set at runtime.
 
 **Help Improve This Documentation**