Improve typehint

src/AuditReader.php

@@ -23,6 +23,7 @@
 use Doctrine\ORM\Mapping\QuoteStrategy;
 use Doctrine\ORM\ORMException;
 use Doctrine\ORM\PersistentCollection;
+use Doctrine\ORM\Persisters\Entity\EntityPersister;
 use Doctrine\ORM\Query;
 use SimpleThings\EntityAudit\Collection\AuditedCollection;
 use SimpleThings\EntityAudit\Exception\DeletedException;
@@ -199,9 +200,9 @@ public function clearEntityCache(): void
      * returns last revision INCLUDING "DEL" revision. If you want to throw exception instead, set
      * $threatDeletionAsException to true.
      *
-     * @param string $className
-     * @param mixed  $id
-     * @param int    $revision
+     * @param string           $className
+     * @param int|string|array $id
+     * @param int|string       $revision
      *
      * @throws DeletedException
      * @throws NoRevisionFoundException
@@ -211,6 +212,10 @@ public function clearEntityCache(): void
      * @throws \RuntimeException
      *
      * @return object
+     *
+     * @phpstan-template T of object
+     * @phpstan-param class-string<T> $className
+     * @phpstan-return T|null
      */
     public function find($className, $id, $revision, array $options = [])
     {
@@ -363,6 +368,10 @@ public function findRevisionHistory($limit = 20, $offset = 0)
      *
      * @deprecated this function name is misspelled.
      * Suggest using findEntitiesChangedAtRevision instead.
+     *
+     * @param string|int $revision
+     *
+     * @return ChangedEntity[]
      */
     public function findEntitesChangedAtRevision($revision)
     {
@@ -372,7 +381,7 @@ public function findEntitesChangedAtRevision($revision)
     /**
      * Return a list of ChangedEntity instances created at the given revision.
      *
-     * @param int $revision
+     * @param string|int $revision
      *
      * @throws DeletedException
      * @throws NoRevisionFoundException
@@ -470,17 +479,17 @@ public function findEntitiesChangedAtRevision($revision)
     /**
      * Return the revision object for a particular revision.
      *
-     * @param int $rev
+     * @param string|int $revision
      *
      * @throws InvalidRevisionException
      * @throws Exception
      *
      * @return Revision
      */
-    public function findRevision($rev)
+    public function findRevision($revision)
     {
         $query = 'SELECT * FROM '.$this->config->getRevisionTableName().' r WHERE r.id = ?';
-        $revisionsData = $this->em->getConnection()->fetchAllAssociative($query, [$rev]);
+        $revisionsData = $this->em->getConnection()->fetchAllAssociative($query, [$revision]);
 
         if (1 === \count($revisionsData)) {
             return new Revision(
@@ -489,19 +498,21 @@ public function findRevision($rev)
                 $revisionsData[0]['username']
             );
         }
-        throw new InvalidRevisionException($rev);
+        throw new InvalidRevisionException($revision);
     }
 
     /**
      * Find all revisions that were made of entity class with given id.
      *
-     * @param string $className
-     * @param mixed  $id
+     * @param string           $className
+     * @param int|string|array $id
      *
      * @throws NotAuditedException
      * @throws Exception
      *
      * @return Revision[]
+     *
+     * @phpstan-param class-string $className
      */
     public function findRevisions($className, $id)
     {
@@ -551,13 +562,15 @@ public function findRevisions($className, $id)
     /**
      * Gets the current revision of the entity with given ID.
      *
-     * @param string $className
-     * @param mixed  $id
+     * @param string           $className
+     * @param int|string|array $id
      *
      * @throws NotAuditedException
      * @throws Exception
      *
-     * @return int
+     * @return int|string
+     *
+     * @phpstan-param class-string $className
      */
     public function getCurrentRevision($className, $id)
     {
@@ -598,10 +611,10 @@ public function getCurrentRevision($className, $id)
      * Get an array with the differences of between two specific revisions of
      * an object with a given id.
      *
-     * @param string $className
-     * @param int    $id
-     * @param int    $oldRevision
-     * @param int    $newRevision
+     * @param string           $className
+     * @param int|string|array $id
+     * @param int|string       $oldRevision
+     * @param int|string       $newRevision
      *
      * @throws DeletedException
      * @throws NoRevisionFoundException
@@ -610,7 +623,10 @@ public function getCurrentRevision($className, $id)
      * @throws ORMException
      * @throws \RuntimeException
      *
-     * @return array
+     * @return array<string, array<string, mixed>>
+     *
+     * @phpstan-param class-string $className
+     * @phpstan-return array<string, array{old: mixed, new: mixed, same: mixed}>
      */
     public function diff($className, $id, $oldRevision, $newRevision)
     {
@@ -632,6 +648,8 @@ public function diff($className, $id, $oldRevision, $newRevision)
      * @param object $entity
      *
      * @return array
+     *
+     * @phpstan-param class-string $className
      */
     public function getEntityValues($className, $entity)
     {
@@ -648,16 +666,18 @@ public function getEntityValues($className, $entity)
     }
 
     /**
-     * @param string $className
-     * @param int    $id
+     * @param string           $className
+     * @param int|string|array $id
      *
      * @throws DeletedException
      * @throws NoRevisionFoundException
      * @throws NotAuditedException
      * @throws Exception
      * @throws ORMException
      *
-     * @return array
+     * @return object[]
+     *
+     * @phpstan-param class-string $className
      */
     public function getEntityHistory($className, $id)
     {
@@ -725,18 +745,25 @@ public function getEntityHistory($className, $id)
         return $result;
     }
 
-    protected function getEntityPersister($entity)
+    /**
+     * @param string $className
+     *
+     * @return EntityPersister
+     *
+     * @phpstan-param class-string $className
+     */
+    protected function getEntityPersister($className)
     {
         $uow = $this->em->getUnitOfWork();
 
-        return $uow->getEntityPersister($entity);
+        return $uow->getEntityPersister($className);
     }
 
     /**
      * Simplified and stolen code from UnitOfWork::createEntity.
      *
-     * @param string $className
-     * @param $revision
+     * @param string     $className
+     * @param int|string $revision
      *
      * @throws DeletedException
      * @throws NoRevisionFoundException
@@ -746,6 +773,10 @@ protected function getEntityPersister($entity)
      * @throws \RuntimeException
      *
      * @return object
+     *
+     * @phpstan-template T of object
+     * @phpstan-param class-string<T> $className
+     * @phpstan-return T
      */
     private function createEntity($className, array $columnMap, array $data, $revision)
     {

src/ChangedEntity.php

@@ -15,12 +15,27 @@
 
 class ChangedEntity
 {
+    /**
+     * @var string
+     */
     private $className;
+
+    /**
+     * @var array
+     */
     private $id;
+
+    /**
+     * @var string
+     */
     private $revType;
+
+    /**
+     * @var object
+     */
     private $entity;
 
-    public function __construct($className, array $id, $revType, $entity)
+    public function __construct(string $className, array $id, string $revType, object $entity)
     {
         $this->className = $className;
         $this->id = $id;

src/DependencyInjection/Configuration.php

@@ -18,6 +18,14 @@
 
 class Configuration implements ConfigurationInterface
 {
+    private const ALLOWED_REVISION_ID_FIELD_TYPE = [
+        'string',
+        'integer',
+        'smallint',
+        'bigint',
+        'guid',
+    ];
+
     public function getConfigTreeBuilder()
     {
         $builder = new TreeBuilder('simple_things_entity_audit');
@@ -36,7 +44,25 @@ public function getConfigTreeBuilder()
                 ->scalarNode('revision_field_name')->defaultValue('rev')->end()
                 ->scalarNode('revision_type_field_name')->defaultValue('revtype')->end()
                 ->scalarNode('revision_table_name')->defaultValue('revisions')->end()
-                ->scalarNode('revision_id_field_type')->defaultValue('integer')->end()
+                ->scalarNode('revision_id_field_type')
+                    ->defaultValue('integer')
+                    // NEXT_MAJOR: Use validate() instead.
+                    ->beforeNormalization()
+                        ->always(static function ($value) {
+                            if (null !== $value && !\in_array($value, self::ALLOWED_REVISION_ID_FIELD_TYPE, true)) {
+                                @trigger_error(sprintf(
+                                    'The value "%s" for the "revision_id_field_type" is deprecated'
+                                    .' since sonata-project/entity-audit-bundle 1.3 and will throw an error in version 2.0.'
+                                    .' You must pass one of the following values: "%s".',
+                                    $value,
+                                    implode('", "', self::ALLOWED_REVISION_ID_FIELD_TYPE)
+                                ), \E_USER_DEPRECATED);
+                            }
+
+                            return $value;
+                        })
+                    ->end()
+                ->end()
                 ->arrayNode('service')
                     ->addDefaultsIfNotSet()
                     ->children()

src/Exception/AuditException.php

@@ -15,13 +15,22 @@
 
 abstract class AuditException extends \Exception
 {
+    /**
+     * @var string|null
+     */
     protected $className;
 
+    /**
+     * @var array|null
+     */
     protected $id;
 
+    /**
+     * @var int|string|null
+     */
     protected $revision;
 
-    public function __construct($className, $id, $revision)
+    public function __construct(?string $className, ?array $id, $revision)
     {
         $this->className = $className;
         $this->id = $id;

src/Exception/AuditedCollectionException.php

@@ -15,7 +15,7 @@
 
 class AuditedCollectionException extends AuditException
 {
-    public function __construct($message)
+    public function __construct(string $message)
     {
         \Exception::__construct($message);
     }

src/Exception/DeletedException.php

@@ -15,9 +15,10 @@
 
 class DeletedException extends AuditException
 {
-    public function __construct($className, $id, $revision)
+    public function __construct(string $className, array $id, $revision)
     {
         parent::__construct($className, $id, $revision);
+
         $this->message = sprintf(
             'Class "%s" entity id "%s" has been removed at revision %s',
             $className,

src/Exception/InvalidRevisionException.php

@@ -18,9 +18,7 @@ class InvalidRevisionException extends AuditException
     public function __construct($revision)
     {
         parent::__construct(null, null, $revision);
-        $this->message = sprintf(
-            'No revision "%s" exists.',
-            $revision
-        );
+
+        $this->message = sprintf('No revision "%s" exists.', $revision);
     }
 }

src/Exception/NoRevisionFoundException.php

@@ -15,9 +15,10 @@
 
 class NoRevisionFoundException extends AuditException
 {
-    public function __construct($className, $id, $revision)
+    public function __construct(string $className, array $id, $revision)
     {
         parent::__construct($className, $id, $revision);
+
         $this->message = sprintf(
             'No revision of class "%s" (%s) was found at revision %s or before. The entity did not exist at the specified revision yet.',
             $className,

src/Exception/NotAuditedException.php

@@ -15,12 +15,10 @@
 
 class NotAuditedException extends AuditException
 {
-    public function __construct($className)
+    public function __construct(string $className)
     {
         parent::__construct($className, null, null);
-        $this->message = sprintf(
-            'Class "%s" is not audited.',
-            $className
-        );
+
+        $this->message = sprintf('Class "%s" is not audited.', $className);
     }
 }

src/Revision.php

@@ -18,11 +18,22 @@
  */
 class Revision
 {
+    /**
+     * @var int|string
+     */
     private $rev;
+
+    /**
+     * @var \DateTime
+     */
     private $timestamp;
+
+    /**
+     * @var string
+     */
     private $username;
 
-    public function __construct($rev, $timestamp, $username)
+    public function __construct($rev, \DateTime $timestamp, string $username)
     {
         $this->rev = $rev;
         $this->timestamp = $timestamp;