diff --git a/CHANGELOG.md b/CHANGELOG.md index d7b6fd7c1c..a7a57e8177 100755 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Backward Compatibility Breaks ### Added ### Changed +* Improved PHPDoc types in `Cluster` namespace by @franmomu [#2109](https://github.com/ruflin/Elastica/pull/2109) ### Deprecated ### Removed ### Fixed diff --git a/src/Cluster/Health.php b/src/Cluster/Health.php index 1e54bcac8d..943af89827 100644 --- a/src/Cluster/Health.php +++ b/src/Cluster/Health.php @@ -11,6 +11,26 @@ * @author Ray Ward * * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html + * + * @phpstan-type HealthData = array{ + * cluster_name: string, + * status: HealthStatus, + * timed_out: bool, + * number_of_nodes: int, + * number_of_data_nodes: int, + * active_primary_shards: int, + * active_shards: int, + * relocating_shards: int, + * initializing_shards: int, + * unassigned_shards: int, + * delayed_unassigned_shards: int, + * number_of_pending_tasks: int, + * number_of_in_flight_fetch: int, + * task_max_waiting_in_queue_millis: int, + * active_shards_percent_as_number: float, + * indices: array>, + * } + * @phpstan-type HealthStatus = 'green'|'yellow'|'red' */ class Health { @@ -20,7 +40,8 @@ class Health protected $_client; /** - * @var array the cluster health data + * @var array + * @phpstan-var HealthData */ protected $_data; @@ -32,6 +53,9 @@ public function __construct(Client $client) /** * Gets the health data. + * + * @return array + * @phpstan-return HealthData */ public function getData(): array { @@ -60,6 +84,7 @@ public function getClusterName(): string * Gets the status of the cluster. * * @return string green, yellow or red + * @phpstan-return HealthStatus */ public function getStatus(): string { @@ -153,15 +178,18 @@ public function getTaskMaxWaitingInQueueMillis(): int return $this->_data['task_max_waiting_in_queue_millis']; } + /** + * TODO: Change to float in version 8.0. + */ public function getActiveShardsPercentAsNumber(): int { - return $this->_data['active_shards_percent_as_number']; + return (int) $this->_data['active_shards_percent_as_number']; } /** * Gets the status of the indices. * - * @return Index[] + * @return array */ public function getIndices(): array { @@ -175,6 +203,9 @@ public function getIndices(): array /** * Retrieves the health data from the cluster. + * + * @return array + * @phpstan-return HealthData */ protected function _retrieveHealthData(): array { diff --git a/src/Cluster/Health/Index.php b/src/Cluster/Health/Index.php index cee0f939f3..ea1715afbc 100644 --- a/src/Cluster/Health/Index.php +++ b/src/Cluster/Health/Index.php @@ -8,6 +8,20 @@ * @author Ray Ward * * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html + * + * @phpstan-import-type HealthStatus from \Elastica\Cluster\Health + * @phpstan-import-type ShardData from Shard + * @phpstan-type IndexData = array{ + * status: HealthStatus, + * number_of_shards: int, + * number_of_replicas: int, + * active_primary_shards: int, + * active_shards: int, + * relocating_shards: int, + * initializing_shards: int, + * unassigned_shards: int, + * shards: ShardData[], + * } */ class Index { @@ -17,13 +31,15 @@ class Index protected $_name; /** - * @var array the index health data + * @var array the index health data + * @phpstan-var IndexData */ protected $_data; /** - * @param string $name the name of the index - * @param array $data the index health data + * @param string $name the name of the index + * @param array $data the index health data + * @phpstan-param IndexData $data */ public function __construct(string $name, array $data) { @@ -43,6 +59,7 @@ public function getName(): string * Gets the status of the index. * * @return string green, yellow or red + * @phpstan-return HealthStatus */ public function getStatus(): string { diff --git a/src/Cluster/Health/Shard.php b/src/Cluster/Health/Shard.php index a945d9f3b8..10808c71f3 100644 --- a/src/Cluster/Health/Shard.php +++ b/src/Cluster/Health/Shard.php @@ -8,6 +8,16 @@ * @author Ray Ward * * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-health.html + * + * @phpstan-import-type HealthStatus from \Elastica\Cluster\Health + * @phpstan-type ShardData = array{ + * status: HealthStatus, + * primary_active: bool, + * active_shards: int, + * relocating_shards: int, + * initializing_shards: int, + * unassigned_shards: int, + * } */ class Shard { @@ -17,13 +27,15 @@ class Shard protected $_shardNumber; /** - * @var array the shard health data + * @var array the shard health data + * @phpstan-var ShardData */ protected $_data; /** - * @param int $shardNumber the shard index/number - * @param array $data the shard health data + * @param int $shardNumber the shard index/number + * @param array $data the shard health data + * @phpstan-param ShardData $data */ public function __construct(int $shardNumber, array $data) { diff --git a/src/Cluster/Settings.php b/src/Cluster/Settings.php index 73c924818e..0c3196265c 100644 --- a/src/Cluster/Settings.php +++ b/src/Cluster/Settings.php @@ -33,7 +33,7 @@ public function __construct(Client $client) /** * Returns settings data. * - * @return array Settings data (persistent and transient) + * @return array Settings data (persistent and transient) */ public function get(): array { @@ -47,7 +47,7 @@ public function get(): array * * @param string $setting OPTIONAL Setting name to return * - * @return array|string|null Settings data + * @return array|string|null Settings data */ public function getPersistent(string $setting = '') { @@ -68,7 +68,7 @@ public function getPersistent(string $setting = '') * * @param string $setting OPTIONAL Setting name to return * - * @return array|string|null Settings data + * @return array|string|null Settings data */ public function getTransient(string $setting = '') { @@ -153,7 +153,7 @@ public function setReadOnly(bool $readOnly = true, bool $persistent = false): Re /** * Set settings for cluster. * - * @param array $settings Raw settings (including persistent or transient) + * @param array $settings Raw settings (including persistent or transient) */ public function set(array $settings): Response { @@ -168,6 +168,9 @@ public function getClient(): Client return $this->_client; } + /** + * @param array $data + */ public function request(array $data = [], string $method = Request::GET): Response { $path = '_cluster/settings';