From 7d46b118f548a84adec476490dc905eccbe58fe1 Mon Sep 17 00:00:00 2001 From: Christophe Coevoet Date: Fri, 9 Aug 2024 22:39:03 +0200 Subject: [PATCH] Add more precise types (#220) Signed-off-by: Christophe Coevoet --- .../Serializer/JsonErrorException.php | 6 ++++- .../ConnectionPool/AbstractConnectionPool.php | 4 ++-- .../ConnectionPool/SimpleConnectionPool.php | 3 ++- .../ConnectionPool/SniffingConnectionPool.php | 9 +++++++- .../ConnectionPool/StaticConnectionPool.php | 3 ++- .../StaticNoPingConnectionPool.php | 3 ++- src/OpenSearch/Connections/Connection.php | 18 +++++++++++---- .../Connections/ConnectionFactory.php | 3 +++ .../ConnectionFactoryInterface.php | 3 +++ .../Connections/ConnectionInterface.php | 3 ++- src/OpenSearch/Endpoints/AbstractEndpoint.php | 13 ++++++++--- src/OpenSearch/Handlers/SigV4Handler.php | 23 +++++++++++++++++++ src/OpenSearch/Transport.php | 2 +- tests/ClientIntegrationTest.php | 2 +- tests/Handlers/SigV4HandlerTest.php | 3 +++ tests/Utility.php | 5 +++- 16 files changed, 85 insertions(+), 18 deletions(-) diff --git a/src/OpenSearch/Common/Exceptions/Serializer/JsonErrorException.php b/src/OpenSearch/Common/Exceptions/Serializer/JsonErrorException.php index 108d3087..2456ae8c 100644 --- 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 index b92bc0d2..7d0ea6a6 100644 --- 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 */ 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 $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 index 606d8d3f..29c14d26 100644 --- 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 $connectionPoolParams */ public function __construct($connections, SelectorInterface $selector, ConnectionFactoryInterface $factory, $connectionPoolParams) { diff --git a/src/OpenSearch/ConnectionPool/SniffingConnectionPool.php b/src/OpenSearch/ConnectionPool/SniffingConnectionPool.php index 41efe6a2..2c6d6b83 100644 --- 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 $connectionPoolParams */ public function __construct( $connections, @@ -148,6 +149,9 @@ private function sniffConnection(Connection $connection): bool return true; } + /** + * @return list + */ private function parseClusterState($nodeInfo): array { $pattern = '/([^:]*):(\d+)/'; @@ -167,6 +171,9 @@ private function parseClusterState($nodeInfo): array return $hosts; } + /** + * @param array $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 index a2a4a946..c074e8c8 100644 --- 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 $connectionPoolParams */ public function __construct($connections, SelectorInterface $selector, ConnectionFactoryInterface $factory, $connectionPoolParams) { diff --git a/src/OpenSearch/ConnectionPool/StaticNoPingConnectionPool.php b/src/OpenSearch/ConnectionPool/StaticNoPingConnectionPool.php index 7208f3b9..a4a85e32 100644 --- 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 $connectionPoolParams */ public function __construct($connections, SelectorInterface $selector, ConnectionFactoryInterface $factory, $connectionPoolParams) { diff --git a/src/OpenSearch/Connections/Connection.php b/src/OpenSearch/Connections/Connection.php index 3a67e930..c81861f8 100644 --- 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> */ 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>, curl?: array}} $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 $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|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> + */ public function getHeaders(): array { return $this->headers; diff --git a/src/OpenSearch/Connections/ConnectionFactory.php b/src/OpenSearch/Connections/ConnectionFactory.php index be7b1ddc..f95c2f29 100644 --- 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>, curl?: array}} $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 index c7541cc1..da209abd 100644 --- 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 index 7b61bc81..0a5adcf5 100644 --- 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|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 index db1d7942..0b049dae 100644 --- 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 $params * * @throws UnexpectedValueException */ @@ -218,7 +220,7 @@ private function checkUserParams(array $params) } /** - * @param array $params Note: this is passed by-reference! + * @param array $params Note: this is passed by-reference! */ private function extractOptions(&$params) { @@ -248,6 +250,11 @@ private function extractOptions(&$params) } } + /** + * @param array $params + * + * @return array + */ 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 */ diff --git a/src/OpenSearch/Handlers/SigV4Handler.php b/src/OpenSearch/Handlers/SigV4Handler.php index 41bc8b8c..b40613b4 100644 --- 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>, body: string|resource|null, client?: array} + */ 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 index 8655ce5e..df6b5b98 100644 --- 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 $params Optional query parameters * @param mixed|null $body Optional query body * @param array $options * diff --git a/tests/ClientIntegrationTest.php b/tests/ClientIntegrationTest.php index c52d9971..2fd5c391 100644 --- 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 index 862043b2..1b255e65 100644 --- 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 + */ private $envTemp = []; protected function setUp(): void diff --git a/tests/Utility.php b/tests/Utility.php index 7ca46e2d..bf004660 100644 --- 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)) {