Add type declarations where backwards-compatible

This includes:
- private methods
- return type declarations of final protected methods
- return type declarations of public and protected methods of final classes

Parameter type declarations are a more delicate matter and should
probably be handled separately to make it easier to catch issues during
code review.

Type declarations can be more trusted than simple phpdoc when it
comes to static analysis, having them means we can infer the phpdoc of
calling methods with confidence.

Note that it seems that some of the phpdoc I initially inferred these
declarations from were apparently wrong, in particular some mentioning
Doctrine\Dbal\Statement when was is really passed around is
Doctrine\Dbal\Driver\Statement.

lib/Doctrine/ORM/AbstractQuery.php

@@ -507,10 +507,8 @@ protected function getResultSetMapping()
 
     /**
      * Allows to translate entity namespaces to full qualified names.
-     *
-     * @return void
      */
-    private function translateNamespaces(Query\ResultSetMapping $rsm)
+    private function translateNamespaces(Query\ResultSetMapping $rsm): void
     {
         $translate = function ($alias): string {
             return $this->_em->getClassMetadata($alias)->getName();
@@ -1137,10 +1135,7 @@ private function executeUsingQueryCache($parameters = null, $hydrationMode = nul
         return $result;
     }
 
-    /**
-     * @return TimestampCacheKey|null
-     */
-    private function getTimestampKey()
+    private function getTimestampKey(): ?TimestampCacheKey
     {
         $entityName = reset($this->_resultSetMapping->aliasMap);
 

lib/Doctrine/ORM/Cache/DefaultCache.php

@@ -278,10 +278,8 @@ public function getQueryCache($regionName = null)
      /**
       * @param ClassMetadata $metadata   The entity metadata.
       * @param mixed         $identifier The entity identifier.
-      *
-      * @return EntityCacheKey
       */
-    private function buildEntityCacheKey(ClassMetadata $metadata, $identifier)
+    private function buildEntityCacheKey(ClassMetadata $metadata, $identifier): EntityCacheKey
     {
         if (! is_array($identifier)) {
             $identifier = $this->toIdentifierArray($metadata, $identifier);
@@ -294,11 +292,12 @@ private function buildEntityCacheKey(ClassMetadata $metadata, $identifier)
      * @param ClassMetadata $metadata        The entity metadata.
      * @param string        $association     The field name that represents the association.
      * @param mixed         $ownerIdentifier The identifier of the owning entity.
-     *
-     * @return CollectionCacheKey
      */
-    private function buildCollectionCacheKey(ClassMetadata $metadata, $association, $ownerIdentifier)
-    {
+    private function buildCollectionCacheKey(
+        ClassMetadata $metadata,
+        string $association,
+        $ownerIdentifier
+    ): CollectionCacheKey {
         if (! is_array($ownerIdentifier)) {
             $ownerIdentifier = $this->toIdentifierArray($metadata, $ownerIdentifier);
         }
@@ -312,7 +311,7 @@ private function buildCollectionCacheKey(ClassMetadata $metadata, $association,
      *
      * @return array<string, mixed>
      */
-    private function toIdentifierArray(ClassMetadata $metadata, $identifier)
+    private function toIdentifierArray(ClassMetadata $metadata, $identifier): array
     {
         if (is_object($identifier) && $this->em->getMetadataFactory()->hasMetadataFor(ClassUtils::getClass($identifier))) {
             $identifier = $this->uow->getSingleIdentifierValue($identifier);

lib/Doctrine/ORM/Cache/DefaultCacheFactory.php

@@ -207,12 +207,7 @@ public function getRegion(array $cache)
         return $this->regions[$cache['region']] = $region;
     }
 
-    /**
-     * @param string $name
-     *
-     * @return CacheAdapter
-     */
-    private function createRegionCache($name)
+    private function createRegionCache(string $name): CacheAdapter
     {
         $cacheAdapter = clone $this->cache;
 

lib/Doctrine/ORM/Cache/DefaultQueryCache.php

@@ -344,11 +344,9 @@ public function put(QueryCacheKey $key, ResultSetMapping $rsm, $result, array $h
      * @param array<string,mixed> $assoc
      * @param mixed               $assocValue
      *
-     * @return mixed[]|null
-     *
      * @psalm-return array{targetEntity: string, type: mixed, list?: array[], identifier?: array}|null
      */
-    private function storeAssociationCache(QueryCacheKey $key, array $assoc, $assocValue)
+    private function storeAssociationCache(QueryCacheKey $key, array $assoc, $assocValue): ?array
     {
         $assocPersister = $this->uow->getEntityPersister($assoc['targetEntity']);
         $assocMetadata  = $assocPersister->getClassMetadata();
@@ -398,13 +396,13 @@ private function storeAssociationCache(QueryCacheKey $key, array $assoc, $assocV
     }
 
     /**
-     * @param string $assocAlias
-     * @param object $entity
-     *
      * @return array<object>|object
      */
-    private function getAssociationValue(ResultSetMapping $rsm, $assocAlias, $entity)
-    {
+    private function getAssociationValue(
+        ResultSetMapping $rsm,
+        string $assocAlias,
+        object $entity
+    ) {
         $path  = [];
         $alias = $assocAlias;
 

lib/Doctrine/ORM/Cache/Persister/Entity/AbstractEntityPersister.php

@@ -223,10 +223,7 @@ public function storeEntityCache($entity, EntityCacheKey $key)
         return $cached;
     }
 
-    /**
-     * @param object $entity
-     */
-    private function storeJoinedAssociations($entity)
+    private function storeJoinedAssociations(object $entity): void
     {
         if ($this->joinedAssociations === null) {
             $associations = [];

lib/Doctrine/ORM/Cache/Persister/Entity/NonStrictReadWriteCachedEntityPersister.php

@@ -98,13 +98,7 @@ public function update($entity)
         $this->queuedCache['update'][] = $entity;
     }
 
-    /**
-     * @param object $entity
-     * @param bool   $isChanged
-     *
-     * @return bool
-     */
-    private function updateCache($entity, $isChanged)
+    private function updateCache(object $entity, bool $isChanged): ?bool
     {
         $class     = $this->metadataFactory->getMetadataFor(get_class($entity));
         $key       = new EntityCacheKey($class->rootEntityName, $this->uow->getEntityIdentifier($entity));

lib/Doctrine/ORM/Cache/Region/FileLockRegion.php

@@ -83,10 +83,7 @@ public function __construct(Region $region, $directory, $lockLifetime)
         $this->lockLifetime = $lockLifetime;
     }
 
-    /**
-     * @return bool
-     */
-    private function isLocked(CacheKey $key, ?Lock $lock = null)
+    private function isLocked(CacheKey $key, ?Lock $lock = null): bool
     {
         $filename = $this->getLockFileName($key);
 
@@ -117,30 +114,23 @@ private function isLocked(CacheKey $key, ?Lock $lock = null)
         return true;
     }
 
-    /**
-     * @return string
-     */
-    private function getLockFileName(CacheKey $key)
+    private function getLockFileName(CacheKey $key): string
     {
         return $this->directory . DIRECTORY_SEPARATOR . $key->hash . '.' . self::LOCK_EXTENSION;
     }
 
     /**
-     * @param string $filename
-     *
-     * @return string
+     * @return string|false
      */
-    private function getLockContent($filename)
+    private function getLockContent(string $filename)
     {
         return @file_get_contents($filename);
     }
 
     /**
-     * @param string $filename
-     *
-     * @return int
+     * @return int|false
      */
-    private function getLockTime($filename)
+    private function getLockTime(string $filename)
     {
         return @fileatime($filename);
     }

lib/Doctrine/ORM/Cache/TimestampQueryCacheValidator.php

@@ -48,10 +48,7 @@ public function isValid(QueryCacheKey $key, QueryCacheEntry $entry)
         return $entry->time + $key->lifetime > microtime(true);
     }
 
-    /**
-     * @return bool
-     */
-    private function regionUpdated(QueryCacheKey $key, QueryCacheEntry $entry)
+    private function regionUpdated(QueryCacheKey $key, QueryCacheEntry $entry): bool
     {
         if ($key->timestampKey === null) {
             return false;

lib/Doctrine/ORM/EntityManager.php

@@ -799,11 +799,9 @@ public function getConfiguration()
     /**
      * Throws an exception if the EntityManager is closed or currently not active.
      *
-     * @return void
-     *
      * @throws ORMException If the EntityManager is closed.
      */
-    private function errorIfClosed()
+    private function errorIfClosed(): void
     {
         if ($this->closed) {
             throw ORMException::entityManagerClosed();

lib/Doctrine/ORM/Event/PreUpdateEventArgs.php

@@ -113,13 +113,9 @@ public function setNewValue($field, $value)
     /**
      * Asserts the field exists in changeset.
      *
-     * @param string $field
-     *
-     * @return void
-     *
      * @throws InvalidArgumentException
      */
-    private function assertValidField($field)
+    private function assertValidField(string $field): void
     {
         if (! isset($this->entityChangeSet[$field])) {
             throw new InvalidArgumentException(sprintf(

lib/Doctrine/ORM/Internal/CommitOrderCalculator.php

@@ -146,10 +146,8 @@ public function sort()
      * Visit a given node definition for reordering.
      *
      * {@internal Highly performance-sensitive method.}
-     *
-     * @param stdClass $vertex
      */
-    private function visit($vertex)
+    private function visit(stdClass $vertex): void
     {
         $vertex->state = self::IN_PROGRESS;
 

lib/Doctrine/ORM/Internal/Hydration/ArrayHydrator.php

@@ -261,13 +261,14 @@ protected function hydrateRowData(array $row, array &$result)
      *
      * @param mixed[]  $coll     The element.
      * @param bool|int $index    Index of the element in the collection.
-     * @param string   $dqlAlias
      * @param bool     $oneToOne Whether it is a single-valued association or not.
-     *
-     * @return void
      */
-    private function updateResultPointer(array &$coll, $index, $dqlAlias, $oneToOne)
-    {
+    private function updateResultPointer(
+        array &$coll,
+        $index,
+        string $dqlAlias,
+        bool $oneToOne
+    ): void {
         if ($coll === null) {
             unset($this->_resultPointers[$dqlAlias]); // Ticket #1228
 

lib/Doctrine/ORM/Internal/Hydration/ObjectHydrator.php

@@ -171,15 +171,16 @@ protected function hydrateAllData()
     /**
      * Initializes a related collection.
      *
-     * @param object        $entity         The entity to which the collection belongs.
-     * @param ClassMetadata $class
-     * @param string        $fieldName      The name of the field on the entity that holds the collection.
-     * @param string        $parentDqlAlias Alias of the parent fetch joining this collection.
-     *
-     * @return PersistentCollection
+     * @param object $entity         The entity to which the collection belongs.
+     * @param string $fieldName      The name of the field on the entity that holds the collection.
+     * @param string $parentDqlAlias Alias of the parent fetch joining this collection.
      */
-    private function initRelatedCollection($entity, $class, $fieldName, $parentDqlAlias)
-    {
+    private function initRelatedCollection(
+        object $entity,
+        ClassMetadata $class,
+        string $fieldName,
+        string $parentDqlAlias
+    ): PersistentCollection {
         $oid      = spl_object_hash($entity);
         $relation = $class->associationMappings[$fieldName];
         $value    = $class->reflFields[$fieldName]->getValue($entity);
@@ -224,13 +225,11 @@ private function initRelatedCollection($entity, $class, $fieldName, $parentDqlAl
      *
      * @param string $dqlAlias The DQL alias of the entity's class.
      *
-     * @return object The entity.
-     *
      * @throws HydrationException
      *
      * @psalm-param array<string, mixed> $data     The instance data.
      */
-    private function getEntity(array $data, $dqlAlias)
+    private function getEntity(array $data, string $dqlAlias): object
     {
         $className = $this->_rsm->aliasMap[$dqlAlias];
 
@@ -273,13 +272,11 @@ private function getEntity(array $data, $dqlAlias)
     }
 
     /**
-     * @param string $className
-     *
      * @return mixed
      *
      * @psalm-param array<string, mixed> $data
      */
-    private function getEntityFromIdentityMap($className, array $data)
+    private function getEntityFromIdentityMap(string $className, array $data)
     {
         // TODO: Abstract this code and UnitOfWork::createEntity() equivalent?
         $class = $this->_metadataCache[$className];

lib/Doctrine/ORM/Internal/HydrationCompleteHandler.php

@@ -55,7 +55,7 @@ public function __construct(ListenersInvoker $listenersInvoker, EntityManagerInt
      *
      * @param object $entity
      */
-    public function deferPostLoadInvoking(ClassMetadata $class, $entity)
+    public function deferPostLoadInvoking(ClassMetadata $class, $entity): void
     {
         $invoke = $this->listenersInvoker->getSubscribedSystems($class, Events::postLoad);
 
@@ -71,7 +71,7 @@ public function deferPostLoadInvoking(ClassMetadata $class, $entity)
      *
      * Method fires all deferred invocations of postLoad events
      */
-    public function hydrationComplete()
+    public function hydrationComplete(): void
     {
         $toInvoke                          = $this->deferredPostLoadInvocations;
         $this->deferredPostLoadInvocations = [];