From a800c2a0781b162e3c9636cf593fff55483bbe18 Mon Sep 17 00:00:00 2001 From: Vincent Langlet Date: Sun, 4 Apr 2021 21:57:24 +0200 Subject: [PATCH] Improve typehint --- src/AuditReader.php | 81 ++++++++++++++------ src/ChangedEntity.php | 17 +++- src/Exception/AuditException.php | 11 ++- src/Exception/AuditedCollectionException.php | 2 +- src/Exception/DeletedException.php | 3 +- src/Exception/InvalidRevisionException.php | 6 +- src/Exception/NoRevisionFoundException.php | 3 +- src/Exception/NotAuditedException.php | 8 +- src/Revision.php | 13 +++- src/Utils/ArrayDiff.php | 8 ++ 10 files changed, 112 insertions(+), 40 deletions(-) diff --git a/src/AuditReader.php b/src/AuditReader.php index c55a15db..fe3ab108 100644 --- a/src/AuditReader.php +++ b/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 $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> + * + * @phpstan-param class-string $className + * @phpstan-return array */ 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,8 +666,8 @@ public function getEntityValues($className, $entity) } /** - * @param string $className - * @param int $id + * @param string $className + * @param int|string|array $id * * @throws DeletedException * @throws NoRevisionFoundException @@ -657,7 +675,9 @@ public function getEntityValues($className, $entity) * @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 $className + * @phpstan-return T */ private function createEntity($className, array $columnMap, array $data, $revision) { diff --git a/src/ChangedEntity.php b/src/ChangedEntity.php index 7b59bc1e..bbf6fb61 100644 --- a/src/ChangedEntity.php +++ b/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; diff --git a/src/Exception/AuditException.php b/src/Exception/AuditException.php index b77c4f98..7c68aaa8 100644 --- a/src/Exception/AuditException.php +++ b/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; diff --git a/src/Exception/AuditedCollectionException.php b/src/Exception/AuditedCollectionException.php index 5bcf4daf..3800f5e2 100644 --- a/src/Exception/AuditedCollectionException.php +++ b/src/Exception/AuditedCollectionException.php @@ -15,7 +15,7 @@ class AuditedCollectionException extends AuditException { - public function __construct($message) + public function __construct(string $message) { \Exception::__construct($message); } diff --git a/src/Exception/DeletedException.php b/src/Exception/DeletedException.php index c3477878..18bb97ab 100644 --- a/src/Exception/DeletedException.php +++ b/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, diff --git a/src/Exception/InvalidRevisionException.php b/src/Exception/InvalidRevisionException.php index e3e1554e..8e27a563 100644 --- a/src/Exception/InvalidRevisionException.php +++ b/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); } } diff --git a/src/Exception/NoRevisionFoundException.php b/src/Exception/NoRevisionFoundException.php index 7e59bbb7..ea5fbadc 100644 --- a/src/Exception/NoRevisionFoundException.php +++ b/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, diff --git a/src/Exception/NotAuditedException.php b/src/Exception/NotAuditedException.php index 2b26532c..8022a7aa 100644 --- a/src/Exception/NotAuditedException.php +++ b/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); } } diff --git a/src/Revision.php b/src/Revision.php index 9af1d995..c66b5770 100644 --- a/src/Revision.php +++ b/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; diff --git a/src/Utils/ArrayDiff.php b/src/Utils/ArrayDiff.php index cf45d2f8..727d3118 100644 --- a/src/Utils/ArrayDiff.php +++ b/src/Utils/ArrayDiff.php @@ -20,6 +20,14 @@ */ class ArrayDiff { + /** + * @param array $oldData + * @param array $newData + * + * @return array> + * + * @phpstan-return array + */ public function diff($oldData, $newData) { $diff = [];