Improve type declarations in phpdoc (#2328)

lib/Doctrine/ODM/MongoDB/Configuration.php

@@ -44,6 +44,8 @@
  *
  *     $config = new Configuration();
  *     $dm = DocumentManager::create(new Connection(), $config);
+ *
+ * @psalm-import-type CommitOptions from UnitOfWork
  */
 class Configuration
 {
@@ -82,6 +84,25 @@ class Configuration
      * Array of attributes for this configuration instance.
      *
      * @var array
+     * @psalm-var array{
+     *      autoGenerateHydratorClasses?: self::AUTOGENERATE_*,
+     *      autoGeneratePersistentCollectionClasses?: self::AUTOGENERATE_*,
+     *      defaultCommitOptions?: CommitOptions,
+     *      defaultDocumentRepositoryClassName?: string,
+     *      documentNamespaces?: array<string, string>,
+     *      filters?: array<string, array{
+     *          class: string,
+     *          parameters: array<string, mixed>
+     *      }>,
+     *      hydratorDir?: string,
+     *      hydratorNamespace?: string,
+     *      metadataCacheImpl?: Cache,
+     *      metadataDriverImpl?: MappingDriver,
+     *      persistentCollectionFactory?: PersistentCollectionFactory,
+     *      persistentCollectionGenerator?: PersistentCollectionGenerator,
+     *      persistentCollectionDir?: string,
+     *      repositoryFactory?: RepositoryFactory
+     * }
      */
     private $attributes = [];
 
@@ -124,6 +145,8 @@ public function getDocumentNamespace(string $documentNamespaceAlias): string
 
     /**
      * Retrieves the list of registered document namespace aliases.
+     *
+     * @return array<string, string>
      */
     public function getDocumentNamespaces(): array
     {
@@ -132,6 +155,8 @@ public function getDocumentNamespaces(): array
 
     /**
      * Set the document alias map
+     *
+     * @param array<string, string> $documentNamespaces
      */
     public function setDocumentNamespaces(array $documentNamespaces): void
     {
@@ -151,6 +176,8 @@ public function setMetadataDriverImpl(MappingDriver $driverImpl): void
 
     /**
      * Add a new default annotation driver with a correctly configured annotation reader.
+     *
+     * @param string[] $paths
      */
     public function newDefaultAnnotationDriver(array $paths = []): AnnotationDriver
     {
@@ -287,6 +314,8 @@ public function getHydratorDir(): ?string
     /**
      * Gets an int flag that indicates whether hydrator classes should always be regenerated
      * during each script execution.
+     *
+     * @psalm-return self::AUTOGENERATE_*
      */
     public function getAutoGenerateHydratorClasses(): int
     {
@@ -296,6 +325,8 @@ public function getAutoGenerateHydratorClasses(): int
     /**
      * Sets an int flag that indicates whether hydrator classes should always be regenerated
      * during each script execution.
+     *
+     * @psalm-param self::AUTOGENERATE_* $mode
      */
     public function setAutoGenerateHydratorClasses(int $mode): void
     {
@@ -325,6 +356,8 @@ public function getPersistentCollectionDir(): ?string
     /**
      * Gets a integer flag that indicates how and when persistent collection
      * classes should be generated.
+     *
+     * @psalm-return self::AUTOGENERATE_*
      */
     public function getAutoGeneratePersistentCollectionClasses(): int
     {
@@ -334,6 +367,8 @@ public function getAutoGeneratePersistentCollectionClasses(): int
     /**
      * Sets a integer flag that indicates how and when persistent collection
      * classes should be generated.
+     *
+     * @psalm-param self::AUTOGENERATE_* $mode
      */
     public function setAutoGeneratePersistentCollectionClasses(int $mode): void
     {
@@ -381,6 +416,9 @@ public function getClassMetadataFactoryName(): string
         return $this->attributes['classMetadataFactoryName'];
     }
 
+    /**
+     * @psalm-return CommitOptions
+     */
     public function getDefaultCommitOptions(): array
     {
         if (! isset($this->attributes['defaultCommitOptions'])) {
@@ -390,13 +428,19 @@ public function getDefaultCommitOptions(): array
         return $this->attributes['defaultCommitOptions'];
     }
 
+    /**
+     * @psalm-param CommitOptions $defaultCommitOptions
+     */
     public function setDefaultCommitOptions(array $defaultCommitOptions): void
     {
         $this->attributes['defaultCommitOptions'] = $defaultCommitOptions;
     }
 
     /**
      * Add a filter to the list of possible filters.
+     *
+     * @param array<string, mixed> $parameters
+     * @psalm-param class-string $className
      */
     public function addFilter(string $name, string $className, array $parameters = []): void
     {
@@ -413,6 +457,9 @@ public function getFilterClassName(string $name): ?string
             : null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function getFilterParameters(string $name): array
     {
         return isset($this->attributes['filters'][$name])

lib/Doctrine/ODM/MongoDB/DocumentManager.php

@@ -48,6 +48,8 @@
  *
  *     $config = new Configuration();
  *     $dm = DocumentManager::create(new Connection(), $config);
+ *
+ * @psalm-import-type CommitOptions from UnitOfWork
  */
 class DocumentManager implements ObjectManager
 {
@@ -300,6 +302,11 @@ public function getClassNameResolver(): ClassNameResolver
      * Returns the metadata for a class.
      *
      * @param string $className The class name.
+     * @psalm-param class-string<T> $className
+     *
+     * @psalm-return ClassMetadata<T>
+     *
+     * @template T of object
      */
     public function getClassMetadata($className): ClassMetadata
     {
@@ -582,6 +589,7 @@ public function getRepository($className)
      * database.
      *
      * @param array $options Array of options to be used with batchInsert(), update() and remove()
+     * @psalm-param CommitOptions $options
      *
      * @throws MongoDBException
      */
@@ -702,6 +710,8 @@ public function clear($objectName = null)
      * Closes the DocumentManager. All documents that are currently managed
      * by this DocumentManager become detached. The DocumentManager may no longer
      * be used after it is closed.
+     *
+     * @return void
      */
     public function close()
     {

lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php

@@ -99,7 +99,7 @@
  *      isCascadeDetach: bool,
  *      isOwningSide: bool,
  *      isInverseSide: bool,
- *      strategy?: string,
+ *      strategy: string,
  *      association?: int,
  *      id?: bool,
  *      collectionClass?: class-string,
@@ -140,7 +140,7 @@
  *      isInverseSide: bool,
  *      targetDocument: class-string|null,
  *      association: int,
- *      strategy?: string,
+ *      strategy: string,
  *      id?: bool,
  *      collectionClass?: class-string,
  *      cascade?: list<string>|string,

lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php

@@ -71,6 +71,8 @@
  * @internal
  *
  * @template T of object
+ *
+ * @psalm-import-type CommitOptions from UnitOfWork
  */
 final class DocumentPersister
 {
@@ -202,6 +204,8 @@ public function getClassMetadata(): ClassMetadata
      *
      * If no inserts are queued, invoking this method is a NOOP.
      *
+     * @psalm-param CommitOptions $options
+     *
      * @throws DriverException
      */
     public function executeInserts(array $options = []): void
@@ -258,6 +262,8 @@ public function executeInserts(array $options = []): void
      * Queued documents with an ID are upserted individually.
      *
      * If no upserts are queued, invoking this method is a NOOP.
+     *
+     * @psalm-param CommitOptions $options
      */
     public function executeUpserts(array $options = []): void
     {
@@ -354,6 +360,8 @@ private function executeUpsert(object $document, array $options): void
     /**
      * Updates the already persisted document if it has any new changesets.
      *
+     * @psalm-param CommitOptions $options
+     *
      * @throws LockException
      */
     public function update(object $document, array $options = []): void
@@ -417,6 +425,8 @@ public function update(object $document, array $options = []): void
     /**
      * Removes document from mongo
      *
+     * @psalm-param CommitOptions $options
+     *
      * @throws LockException
      */
     public function delete(object $document, array $options = []): void
@@ -1506,6 +1516,9 @@ private function getQueryForDocument(object $document): array
         return array_merge(['_id' => $id], $shardKeyQueryPart);
     }
 
+    /**
+     * @psalm-param CommitOptions $options
+     */
     private function getWriteOptions(array $options = []): array
     {
         $defaultOptions  = $this->dm->getConfiguration()->getDefaultCommitOptions();