Improve PHPDoc types in Cluster

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

src/Cluster/Health.php

@@ -11,6 +11,26 @@
  * @author Ray Ward <[email protected]>
  *
  * @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<string, array<string, mixed>>,
+ * }
+ * @phpstan-type HealthStatus = 'green'|'yellow'|'red'
  */
 class Health
 {
@@ -20,7 +40,8 @@ class Health
     protected $_client;
 
     /**
-     * @var array the cluster health data
+     * @var array<string, mixed>
+     * @phpstan-var HealthData
      */
     protected $_data;
 
@@ -32,6 +53,9 @@ public function __construct(Client $client)
 
     /**
      * Gets the health data.
+     *
+     * @return array<string, mixed>
+     * @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<string, Index>
      */
     public function getIndices(): array
     {
@@ -175,6 +203,9 @@ public function getIndices(): array
 
     /**
      * Retrieves the health data from the cluster.
+     *
+     * @return array<string, mixed>
+     * @phpstan-return HealthData
      */
     protected function _retrieveHealthData(): array
     {

src/Cluster/Health/Index.php

@@ -8,6 +8,20 @@
  * @author Ray Ward <[email protected]>
  *
  * @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<string, mixed> 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<string, mixed> $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
     {

src/Cluster/Health/Shard.php

@@ -8,6 +8,16 @@
  * @author Ray Ward <[email protected]>
  *
  * @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<string, mixed> 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<string, mixed> $data        the shard health data
+     * @phpstan-param ShardData $data
      */
     public function __construct(int $shardNumber, array $data)
     {

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<string, mixed> 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, mixed>|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, mixed>|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<string, mixed> $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<string, mixed> $data
+     */
     public function request(array $data = [], string $method = Request::GET): Response
     {
         $path = '_cluster/settings';