Add more precise types (opensearch-project#220)

Signed-off-by: Christophe Coevoet <[email protected]>
dblock · Aug 9, 2024 · 7d46b11 · 7d46b11
1 parent 73c4b11
commit 7d46b11
Show file tree

Hide file tree

Showing 16 changed files with 85 additions and 18 deletions.
diff --git a/src/OpenSearch/Common/Exceptions/Serializer/JsonErrorException.php b/src/OpenSearch/Common/Exceptions/Serializer/JsonErrorException.php
@@ -56,7 +56,11 @@ class JsonErrorException extends \Exception implements OpenSearchException
         10 => 'Attempted to decode nonexistent UTF-16 code-point' //JSON_ERROR_UTF16
     );
 
-    public function __construct($code, $input, $result, $previous = null)
+    /**
+     * @param mixed $input
+     * @param mixed $result
+     */
+    public function __construct(int $code, $input, $result, \Throwable $previous = null)
     {
         if (isset(self::$messages[$code]) !== true) {
             throw new \InvalidArgumentException(sprintf('Encountered unknown JSON error code: [%d]', $code));

diff --git a/src/OpenSearch/ConnectionPool/AbstractConnectionPool.php b/src/OpenSearch/ConnectionPool/AbstractConnectionPool.php
@@ -50,7 +50,7 @@ abstract class AbstractConnectionPool implements ConnectionPoolInterface
     protected $selector;
 
     /**
-     * @var array
+     * @var array<string, mixed>
      */
     protected $connectionPoolParams;
 
@@ -65,7 +65,7 @@ abstract class AbstractConnectionPool implements ConnectionPoolInterface
      * @param ConnectionInterface[]      $connections          The Connections to choose from
      * @param SelectorInterface          $selector             A Selector instance to perform the selection logic for the available connections
      * @param ConnectionFactoryInterface $factory              ConnectionFactory instance
-     * @param array                      $connectionPoolParams
+     * @param array<string, mixed>       $connectionPoolParams
      */
     public function __construct(array $connections, SelectorInterface $selector, ConnectionFactoryInterface $factory, array $connectionPoolParams)
     {

diff --git a/src/OpenSearch/ConnectionPool/SimpleConnectionPool.php b/src/OpenSearch/ConnectionPool/SimpleConnectionPool.php
@@ -29,7 +29,8 @@
 class SimpleConnectionPool extends AbstractConnectionPool implements ConnectionPoolInterface
 {
     /**
-     * {@inheritdoc}
+     * @param ConnectionInterface[] $connections
+     * @param array<string, mixed>  $connectionPoolParams
      */
     public function __construct($connections, SelectorInterface $selector, ConnectionFactoryInterface $factory, $connectionPoolParams)
     {

diff --git a/src/OpenSearch/ConnectionPool/SniffingConnectionPool.php b/src/OpenSearch/ConnectionPool/SniffingConnectionPool.php
@@ -41,7 +41,8 @@ class SniffingConnectionPool extends AbstractConnectionPool
     private $nextSniff;
 
     /**
-     * {@inheritdoc}
+     * @param ConnectionInterface[] $connections
+     * @param array<string, mixed>  $connectionPoolParams
      */
     public function __construct(
         $connections,
@@ -148,6 +149,9 @@ private function sniffConnection(Connection $connection): bool
         return true;
     }
 
+    /**
+     * @return list<array{host: string, port: int}>
+     */
     private function parseClusterState($nodeInfo): array
     {
         $pattern = '/([^:]*):(\d+)/';
@@ -167,6 +171,9 @@ private function parseClusterState($nodeInfo): array
         return $hosts;
     }
 
+    /**
+     * @param array<string, mixed> $connectionPoolParams
+     */
     private function setConnectionPoolParams(array $connectionPoolParams): void
     {
         $this->sniffingInterval = (int)($connectionPoolParams['sniffingInterval'] ?? 300);

diff --git a/src/OpenSearch/ConnectionPool/StaticConnectionPool.php b/src/OpenSearch/ConnectionPool/StaticConnectionPool.php
@@ -40,7 +40,8 @@ class StaticConnectionPool extends AbstractConnectionPool implements ConnectionP
     private $maxPingTimeout = 3600;
 
     /**
-     * {@inheritdoc}
+     * @param ConnectionInterface[] $connections
+     * @param array<string, mixed>  $connectionPoolParams
      */
     public function __construct($connections, SelectorInterface $selector, ConnectionFactoryInterface $factory, $connectionPoolParams)
     {

diff --git a/src/OpenSearch/ConnectionPool/StaticNoPingConnectionPool.php b/src/OpenSearch/ConnectionPool/StaticNoPingConnectionPool.php
@@ -40,7 +40,8 @@ class StaticNoPingConnectionPool extends AbstractConnectionPool implements Conne
     private $maxPingTimeout = 3600;
 
     /**
-     * {@inheritdoc}
+     * @param ConnectionInterface[] $connections
+     * @param array<string, mixed>  $connectionPoolParams
      */
     public function __construct($connections, SelectorInterface $selector, ConnectionFactoryInterface $factory, $connectionPoolParams)
     {

diff --git a/src/OpenSearch/Connections/Connection.php b/src/OpenSearch/Connections/Connection.php
@@ -95,7 +95,7 @@ class Connection implements ConnectionInterface
     protected $connectionParams;
 
     /**
-     * @var array
+     * @var array<string, list<string>>
      */
     protected $headers = [];
 
@@ -129,6 +129,10 @@ class Connection implements ConnectionInterface
      */
     private $OSVersion = null;
 
+    /**
+     * @param array{host: string, port?: int, scheme?: string, user?: string, pass?: string, path?: string} $hostDetails
+     * @param array{client?: array{headers?: array<string, list<string>>, curl?: array<int, mixed>}} $connectionParams
+     */
     public function __construct(
         callable $handler,
         array $hostDetails,
@@ -192,10 +196,10 @@ public function __construct(
     /**
      * @param  string    $method
      * @param  string    $uri
-     * @param  null|array   $params
-     * @param  null|mixed   $body
+     * @param  null|array<string, mixed> $params
+     * @param  mixed     $body
      * @param  array     $options
-     * @param  Transport $transport
+     * @param  Transport|null $transport
      * @return mixed
      */
     public function performRequest(string $method, string $uri, ?array $params = [], $body = null, array $options = [], Transport $transport = null)
@@ -344,6 +348,9 @@ function ($response) use ($connection, $transport, $request, $options) {
         };
     }
 
+    /**
+     * @param array<string, string|int|bool>|null $params
+     */
     private function getURI(string $uri, ?array $params): string
     {
         if (isset($params) === true && !empty($params)) {
@@ -370,6 +377,9 @@ function ($value) {
         return $uri;
     }
 
+    /**
+     * @return array<string, list<string>>
+     */
     public function getHeaders(): array
     {
         return $this->headers;

diff --git a/src/OpenSearch/Connections/ConnectionFactory.php b/src/OpenSearch/Connections/ConnectionFactory.php
@@ -51,6 +51,9 @@ class ConnectionFactory implements ConnectionFactoryInterface
      */
     private $handler;
 
+    /**
+     * @param array{client?: array{headers?: array<string, list<string>>, curl?: array<int, mixed>}} $connectionParams
+     */
     public function __construct(callable $handler, array $connectionParams, SerializerInterface $serializer, LoggerInterface $logger, LoggerInterface $tracer)
     {
         $this->handler          = $handler;

diff --git a/src/OpenSearch/Connections/ConnectionFactoryInterface.php b/src/OpenSearch/Connections/ConnectionFactoryInterface.php
@@ -23,5 +23,8 @@
 
 interface ConnectionFactoryInterface
 {
+    /**
+     * @param array{host: string, port?: int, scheme?: string, user?: string, pass?: string, path?: string} $hostDetails
+     */
     public function create(array $hostDetails): ConnectionInterface;
 }
diff --git a/src/OpenSearch/Connections/ConnectionInterface.php b/src/OpenSearch/Connections/ConnectionInterface.php
@@ -75,7 +75,8 @@ public function markDead(): void;
     public function getLastRequestInfo(): array;
 
     /**
-     * @param  null $body
+     * @param array<string, mixed>|null $params
+     * @param  mixed $body
      * @return mixed
      */
     public function performRequest(string $method, string $uri, ?array $params = [], $body = null, array $options = [], Transport $transport = null);

diff --git a/src/OpenSearch/Endpoints/AbstractEndpoint.php b/src/OpenSearch/Endpoints/AbstractEndpoint.php
@@ -113,6 +113,8 @@ public function getIndex(): ?string
     }
 
     /**
+     * @param string|string[]|null $index
+     *
      * @return $this
      */
     public function setIndex($index)
@@ -188,7 +190,7 @@ private function getOptionalIndex(): string
     }
 
     /**
-     * @param array $params
+     * @param array<string, mixed> $params
      *
      * @throws UnexpectedValueException
      */
@@ -218,7 +220,7 @@ private function checkUserParams(array $params)
     }
 
     /**
-     * @param array $params Note: this is passed by-reference!
+     * @param array<string, mixed> $params Note: this is passed by-reference!
      */
     private function extractOptions(&$params)
     {
@@ -248,6 +250,11 @@ private function extractOptions(&$params)
         }
     }
 
+    /**
+     * @param array<string, mixed> $params
+     *
+     * @return array<string, mixed>
+     */
     private function convertCustom(array $params): array
     {
         if (isset($params['custom']) === true) {
@@ -285,7 +292,7 @@ private function isNestedArray(array $a): bool
     }
 
     /**
-     * This function returns all param deprecations also optional with an replacement field
+     * This function returns all param deprecations also optional with a replacement field
      *
      * @return array<string, string|null>
      */

diff --git a/src/OpenSearch/Handlers/SigV4Handler.php b/src/OpenSearch/Handlers/SigV4Handler.php
@@ -13,10 +13,22 @@
 use Psr\Http\Message\RequestInterface;
 use RuntimeException;
 
+/**
+ * @phpstan-type RingPhpRequest array{http_method: string, scheme: string, uri: string, query_string?: string, version?: string, headers: array<string, list<string>>, body: string|resource|null, client?: array<string, mixed>}
+ */
 class SigV4Handler
 {
+    /**
+     * @var SignatureV4
+     */
     private $signer;
+    /**
+     * @var callable
+     */
     private $credentialProvider;
+    /**
+     * @var callable
+     */
     private $wrappedHandler;
 
     /**
@@ -46,6 +58,9 @@ public function __construct(
             ?: CredentialProvider::defaultProvider();
     }
 
+    /**
+     * @phpstan-param RingPhpRequest $request
+     */
     public function __invoke(array $request)
     {
         $creds = call_user_func($this->credentialProvider)->wait();
@@ -66,6 +81,9 @@ public static function assertDependenciesInstalled(): void
         }
     }
 
+    /**
+     * @phpstan-param RingPhpRequest $ringPhpRequest
+     */
     private function createPsr7Request(array $ringPhpRequest): Request
     {
         // fix for uppercase 'Host' array key in elasticsearch-php 5.3.1 and backward compatible
@@ -96,6 +114,11 @@ private function createPsr7Request(array $ringPhpRequest): Request
         );
     }
 
+    /**
+     * @phpstan-param RingPhpRequest $originalRequest
+     *
+     * @phpstan-return RingPhpRequest
+     */
     private function createRingRequest(RequestInterface $request, array $originalRequest): array
     {
         $uri = $request->getUri();

diff --git a/src/OpenSearch/Transport.php b/src/OpenSearch/Transport.php
@@ -90,7 +90,7 @@ public function getConnection(): ConnectionInterface
      *
      * @param string     $method  HTTP method to use
      * @param string     $uri     HTTP URI to send request to
-     * @param array      $params  Optional query parameters
+     * @param array<string, mixed> $params  Optional query parameters
      * @param mixed|null $body    Optional query body
      * @param array      $options
      *

diff --git a/tests/ClientIntegrationTest.php b/tests/ClientIntegrationTest.php
@@ -38,7 +38,7 @@
 class ClientIntegrationTest extends \PHPUnit\Framework\TestCase
 {
     /**
-     * ArrayLogger
+     * @var ArrayLogger
      */
     private $logger;
 

diff --git a/tests/Handlers/SigV4HandlerTest.php b/tests/Handlers/SigV4HandlerTest.php
@@ -15,6 +15,9 @@ class SigV4HandlerTest extends TestCase
 {
     private const ENV_KEYS_USED = [CredentialProvider::ENV_KEY, CredentialProvider::ENV_SECRET];
 
+    /**
+     * @var array<string, string|false>
+     */
     private $envTemp = [];
 
     protected function setUp(): void

diff --git a/tests/Utility.php b/tests/Utility.php
@@ -29,7 +29,7 @@
 class Utility
 {
     /**
-     * @var array|null
+     * @var array{number: string, distribution?: string, build_flavor: string, build_date: string, build_hash: string, build_snapshot: bool, build_type: string, lucene_version: string, minimum_index_compatibility_version: string, minimum_wire_compatibility_version: string}|null
      */
     private static $version;
 
@@ -82,6 +82,9 @@ public static function isOpenSearchVersionAtLeast(Client $client, string $versio
         return version_compare($versionNumber, $version, '>=');
     }
 
+    /**
+     * @return array{number: string, distribution?: string, build_flavor: string, build_date: string, build_hash: string, build_snapshot: bool, build_type: string, lucene_version: string, minimum_index_compatibility_version: string, minimum_wire_compatibility_version: string}
+     */
     private static function getVersion(Client $client): array
     {
         if (!isset(self::$version)) {