Generate valid phpdoc param tags (#1457)

* Fix the phpdoc of the RequestContext

* Generate valid phpdoc param tags

When an array shape key starts with a `@` like `@region`, it must be
quoted in the phpdoc as the unquoted one would be interpreted as the
next phpdoc tag.

* Use an unsealed shape for the type in Input

This avoids reports about passing extra keys from child classes in
Psalm.

* Allow passing null as the region in the input

The base input class already accept null values in addition to omitted
values for the region.

* Update the psalm baseline

* Disallow invalid docblocks in Psalm as well

Author: stof

phpstan.neon.dist

@@ -17,8 +17,8 @@ parameters:
         - src/Integration/Laravel/Filesystem/src/AsyncAwsFilesystemAdapter.php
 
     ignoreErrors:
-        - '#^PHPDoc tag @param has invalid value#'
         - '#^Parameter \#1 \$input of class AsyncAws\\[^\\]+\\ValueObject\\[^ ]+ constructor expects (array\(\)\|)?array\([^\)]+\), array\([^\)]+\) given\.#'
+        - '#^Parameter \#1 \$input of method AsyncAws\\DynamoDb\\DynamoDbClient::\w+\(\) expects array\{[^\)]+\}\|AsyncAws\\DynamoDb\\Input\\\w+Input, array\{[^\)]+\} given\.#'
         - '#Method AsyncAws\\[^:]+::[^(]+\(\) should return array<[^>]+> but returns array<int(\|string)?, string>\.$#'
         - '#PHPDoc tag @throws with type Psr\\Cache\\CacheException is not subtype of Throwable$#'
         - '#^Dead catch - JsonException is never thrown in the try block\.$#'

psalm.baseline.xml

@@ -1,5 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <files psalm-version="5.1.0@4defa177c89397c5e14737a80fe4896584130674">
+  <file src="src/Core/src/AbstractApi.php">
+    <UndefinedFunction occurrences="2">
+      <code>trigger_deprecation('async-aws/core', '1.2', 'Extending "%s"" without overriding "%s" is deprecated. This method will be abstract in version 2.0.', __CLASS__, __FUNCTION__)</code>
+      <code>trigger_deprecation('async-aws/core', '1.2', 'providing an endpoint with placeholder is deprecated and will be ignored in version 2.0. Provide full endpoint instead.')</code>
+    </UndefinedFunction>
+  </file>
   <file src="src/Core/src/Credentials/PsrCacheProvider.php">
     <InvalidCatch occurrences="1"/>
     <InvalidThrow occurrences="1">
@@ -27,7 +33,22 @@
       <code>$exception</code>
     </PossiblyUndefinedVariable>
   </file>
+  <file src="src/Integration/Aws/DynamoDbSession/src/SessionHandler.php">
+    <ArgumentTypeCoercion occurrences="6">
+      <code>['TableName' =&gt; $this-&gt;options['table_name']]</code>
+    </ArgumentTypeCoercion>
+  </file>
+  <file src="src/Integration/Aws/SimpleS3/src/SimpleS3Client.php">
+    <ArgumentTypeCoercion occurrences="1"/>
+    <InvalidArgument occurrences="2">
+      <code>array_merge($options, ['Bucket' =&gt; $bucket, 'Key' =&gt; $key])</code>
+    </InvalidArgument>
+  </file>
+  <file src="src/Integration/Flysystem/S3/src/AsyncAwsS3Adapter.php">
+    <InvalidArgument occurrences="2"/>
+  </file>
   <file src="src/Integration/Laravel/Cache/src/AsyncAwsDynamoDbStore.php">
+    <InvalidArgument occurrences="7"/>
     <RedundantCast occurrences="1">
       <code>(int) $e-&gt;getCode()</code>
     </RedundantCast>
@@ -52,13 +73,23 @@
     </UndefinedInterfaceMethod>
   </file>
   <file src="src/Integration/Laravel/Mail/src/Transport/AsyncAwsSesTransport.php">
-    <InvalidArgument occurrences="1"/>
+    <InvalidArgument occurrences="2">
+      <code>array_merge($this-&gt;options, $input)</code>
+    </InvalidArgument>
+  </file>
+  <file src="src/Integration/Laravel/Queue/src/Job/AsyncAwsSqsJob.php">
+    <ArgumentTypeCoercion occurrences="2"/>
   </file>
   <file src="src/Integration/Laravel/Queue/src/ServiceProvider.php">
     <UndefinedInterfaceMethod occurrences="1">
       <code>$this-&gt;app</code>
     </UndefinedInterfaceMethod>
   </file>
+  <file src="src/Integration/Monolog/CloudWatch/src/CloudWatchLogsHandler.php">
+    <ArgumentTypeCoercion occurrences="1">
+      <code>$data</code>
+    </ArgumentTypeCoercion>
+  </file>
   <file src="src/Integration/Symfony/Bundle/src/DependencyInjection/Configuration.php">
     <PossiblyNullReference occurrences="1">
       <code>scalarNode</code>

psalm.xml

@@ -41,7 +41,6 @@
         <MissingClosureReturnType errorLevel="info" />
         <MissingReturnType errorLevel="info" />
         <MissingPropertyType errorLevel="info" />
-        <InvalidDocblock errorLevel="info" />
 
         <PropertyNotSetInConstructor errorLevel="info" />
         <MissingConstructor errorLevel="info" />

src/CodeGenerator/src/Generator/InputGenerator.php

@@ -278,7 +278,7 @@ public function generate(Operation $operation): ClassName
 
         $constructorBody .= 'parent::__construct($input);';
         $constructor = $classBuilder->addMethod('__construct');
-        [$doc, $memberClassNames] = $this->typeGenerator->generateDocblock($shape, $className, false, true, false, ['  @region?: string,']);
+        [$doc, $memberClassNames] = $this->typeGenerator->generateDocblock($shape, $className, false, true, false, ['  \'@region\'?: string|null,']);
         $constructor->addComment($doc);
         foreach ($memberClassNames as $memberClassName) {
             $classBuilder->addUse($memberClassName->getFqdn());

src/CodeGenerator/src/Generator/OperationGenerator.php

@@ -119,7 +119,7 @@ public function generate(Operation $operation): void
         if (null !== $prefix = $operation->getService()->getEndpointPrefix()) {
             $method->addComment('@see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-' . $prefix . '-' . $operation->getService()->getApiVersion() . '.html#' . strtolower($operation->getName()));
         }
-        [$doc, $memberClassNames] = $this->typeGenerator->generateDocblock($inputShape, $inputClass, true, false, false, ['  @region?: string,']);
+        [$doc, $memberClassNames] = $this->typeGenerator->generateDocblock($inputShape, $inputClass, true, false, false, ['  \'@region\'?: string|null,']);
         $method->addComment($doc);
         foreach ($memberClassNames as $memberClassName) {
             $classBuilder->addUse($memberClassName->getFqdn());

src/CodeGenerator/src/Generator/WaiterGenerator.php

@@ -99,7 +99,7 @@ private function generateMethod(ClassBuilder $classBuilder, Waiter $waiter, Oper
         $resultClass = $this->generateWaiterResult($waiter);
         $classBuilder->addUse($resultClass->getFqdn());
 
-        [$doc, $memberClassNames] = $this->typeGenerator->generateDocblock($inputShape, $inputClass, true, false, false, ['  @region?: string,']);
+        [$doc, $memberClassNames] = $this->typeGenerator->generateDocblock($inputShape, $inputClass, true, false, false, ['  \'@region\'?: string|null,']);
 
         $mapping = [];
         foreach ($operation->getErrors() as $error) {

src/Core/src/Input.php

@@ -17,10 +17,7 @@ abstract class Input
     public $region;
 
     /**
-     * @param array{
-     *
-     *   @region?: ?string,
-     * } $input
+     * @param array{'@region'?: ?string,...} $input
      */
     protected function __construct(array $input)
     {

src/Core/src/RequestContext.php

@@ -60,14 +60,14 @@ class RequestContext
 
     /**
      * @param array{
-     *  operation?: null|string
-     *  region?: null|string
-     *  expirationDate?: null|\DateTimeImmutable
-     *  currentDate?: null|\DateTimeImmutable
-     *  exceptionMapping?: string[]
-     *  usesEndpointDiscovery?: bool
-     *  requiresEndpointDiscovery?: bool
-     * }
+     *  operation?: null|string,
+     *  region?: null|string,
+     *  expirationDate?: null|\DateTimeImmutable,
+     *  currentDate?: null|\DateTimeImmutable,
+     *  exceptionMapping?: string[],
+     *  usesEndpointDiscovery?: bool,
+     *  requiresEndpointDiscovery?: bool,
+     * } $options
      */
     public function __construct(array $options = [])
     {

src/Core/src/Sts/Input/AssumeRoleRequest.php

@@ -241,8 +241,7 @@ final class AssumeRoleRequest extends Input
      *   SerialNumber?: string,
      *   TokenCode?: string,
      *   SourceIdentity?: string,
-     *
-     *   @region?: string,
+     *   '@region'?: string|null,
      * } $input
      */
     public function __construct(array $input = [])

src/Core/src/Sts/Input/AssumeRoleWithWebIdentityRequest.php

@@ -138,8 +138,7 @@ final class AssumeRoleWithWebIdentityRequest extends Input
      *   PolicyArns?: PolicyDescriptorType[],
      *   Policy?: string,
      *   DurationSeconds?: int,
-     *
-     *   @region?: string,
+     *   '@region'?: string|null,
      * } $input
      */
     public function __construct(array $input = [])