fix: add phpdocs

mtk3d · mtk3d · commit 0f0b586dc1c0 · 2025-05-01T00:13:13.000+02:00
Signed-off-by: Mateusz Cholewka &lt;mateusz@cholewka.com.pl&gt;
diff --git a/src/Prometheus/Storage/AbstractRedis.php b/src/Prometheus/Storage/AbstractRedis.php
@@ -56,7 +56,6 @@ public function wipeStorage(): void
         $searchPattern = '';
 
         $globalPrefix = $this->redis->getOption(RedisClient::OPT_PREFIX);
-        // @phpstan-ignore-next-line false positive, phpstan thinks getOptions returns int
         if (is_string($globalPrefix)) {
             $searchPattern .= $globalPrefix;
         }
@@ -183,15 +182,15 @@ public function updateSummary(array $data): void
         if ($json === false) {
             throw new RuntimeException(json_last_error_msg());
         }
-        $this->redis->setNx($metaKey, $json); /** @phpstan-ignore-line */
+        $this->redis->setNx($metaKey, $json);
 
         // store value key
         $valueKey = $summaryKey.':'.$this->valueKey($data);
         $json = json_encode($this->encodeLabelValues($data['labelValues']));
         if ($json === false) {
             throw new RuntimeException(json_last_error_msg());
         }
-        $this->redis->setNx($valueKey, $json); /** @phpstan-ignore-line */
+        $this->redis->setNx($valueKey, $json);
 
         // trick to handle uniqid collision
         $done = false;
@@ -370,12 +369,10 @@ protected function collectHistograms(): array
 
     protected function removePrefixFromKey(string $key): string
     {
-        // @phpstan-ignore-next-line false positive, phpstan thinks getOptions returns int
         if ($this->redis->getOption(RedisClient::OPT_PREFIX) === null) {
             return $key;
         }
 
-        // @phpstan-ignore-next-line false positive, phpstan thinks getOptions returns int
         return substr($key, strlen($this->redis->getOption(RedisClient::OPT_PREFIX)));
     }
 
diff --git a/src/Prometheus/Storage/Predis.php b/src/Prometheus/Storage/Predis.php
@@ -45,6 +45,7 @@ class Predis extends AbstractRedis
     /**
      * Redis constructor.
      *
+     * @param  mixed[]  $parameters
      * @param  mixed[]  $options
      */
     public function __construct(array $parameters = [], array $options = [])
@@ -71,7 +72,7 @@ public static function fromExistingConnection(Client $client): self
         ];
 
         $self = new self;
-        $self->redis = new PredisClient($client, self::$defaultParameters, $allOptions);
+        $self->redis = new PredisClient($client, $allOptions);
 
         return $self;
     }
diff --git a/src/Prometheus/Storage/RedisClients/PHPRedis.php b/src/Prometheus/Storage/RedisClients/PHPRedis.php
@@ -13,19 +13,28 @@ class PHPRedis implements RedisClient
      */
     private $redis;
 
+    /**
+     * @var mixed[]
+     */
     private $options = [];
 
     /**
      * @var bool
      */
     private $connectionInitialized = false;
 
+    /**
+     * @param  mixed[]  $options
+     */
     public function __construct(\Redis $redis, array $options)
     {
         $this->redis = $redis;
         $this->options = $options;
     }
 
+    /**
+     * @param  mixed[]  $options
+     */
     public static function create(array $options): self
     {
         $redis = new \Redis;
@@ -43,22 +52,22 @@ public function eval(string $script, array $args = [], int $num_keys = 0): void
         $this->redis->eval($script, $args, $num_keys);
     }
 
-    public function set(string $key, mixed $value, mixed $options = null): void
+    public function set(string $key, mixed $value, mixed $options = null): bool
     {
-        $this->redis->set($key, $value, $options);
+        return $this->redis->set($key, $value, $options);
     }
 
     public function setNx(string $key, mixed $value): void
     {
-        $this->redis->setNx($key, $value);
+        $this->redis->setNx($key, $value); /** @phpstan-ignore-line */
     }
 
     public function hSetNx(string $key, string $field, mixed $value): bool
     {
         return $this->redis->hSetNx($key, $field, $value);
     }
 
-    public function sMembers(string $key): array|false
+    public function sMembers(string $key): array
     {
         return $this->redis->sMembers($key);
     }
diff --git a/src/Prometheus/Storage/RedisClients/Predis.php b/src/Prometheus/Storage/RedisClients/Predis.php
@@ -12,17 +12,30 @@ class Predis implements RedisClient
         RedisClient::OPT_PREFIX => 'prefix',
     ];
 
+    /**
+     * @var Client
+     */
     private $client;
 
+    /**
+     * @var mixed[]
+     */
     private $options = [];
 
+    /**
+     * @param  mixed[]  $options
+     */
     public function __construct(Client $redis, array $options)
     {
         $this->client = $redis;
 
         $this->options = $options;
     }
 
+    /**
+     * @param  mixed[]  $parameters
+     * @param  mixed[]  $options
+     */
     public static function create(array $parameters, array $options): self
     {
         $redisClient = new Client($parameters, $options);
@@ -46,11 +59,17 @@ public function eval(string $script, array $args = [], int $num_keys = 0): void
         $this->client->eval($script, $num_keys, ...$args);
     }
 
-    public function set(string $key, mixed $value, mixed $options = null): void
+    public function set(string $key, mixed $value, mixed $options = null): bool
     {
-        $this->client->set($key, $value, ...$this->flattenFlags($options));
+        $result = $this->client->set($key, $value, ...$this->flattenFlags($options));
+
+        return (string) $result === 'OK';
     }
 
+    /**
+     * @param  array<int|string, mixed>  $flags
+     * @return mixed[]
+     */
     private function flattenFlags(array $flags): array
     {
         $result = [];
@@ -73,10 +92,10 @@ public function setNx(string $key, mixed $value): void
 
     public function hSetNx(string $key, string $field, mixed $value): bool
     {
-        return $this->hsetnx($key, $field, $value);
+        return $this->hSetNx($key, $field, $value);
     }
 
-    public function sMembers(string $key): array|false
+    public function sMembers(string $key): array
     {
         return $this->client->smembers($key);
     }
diff --git a/src/Prometheus/Storage/RedisClients/RedisClient.php b/src/Prometheus/Storage/RedisClients/RedisClient.php
@@ -12,22 +12,37 @@ interface RedisClient
 
     public function getOption(int $option): mixed;
 
+    /**
+     * @param  mixed[]  $args
+     */
     public function eval(string $script, array $args = [], int $num_keys = 0): void;
 
-    public function set(string $key, mixed $value, mixed $options = null): void;
+    public function set(string $key, mixed $value, mixed $options = null): bool;
 
     public function setNx(string $key, mixed $value): void;
 
     public function hSetNx(string $key, string $field, mixed $value): bool;
 
-    public function sMembers(string $key): array|false;
+    /**
+     * @return string[]
+     */
+    public function sMembers(string $key): array;
 
+    /**
+     * @return array<string, string>|false
+     */
     public function hGetAll(string $key): array|false;
 
+    /**
+     * @return string[]
+     */
     public function keys(string $pattern);
 
     public function get(string $key): mixed;
 
+    /**
+     * @param  string|string[]  $key
+     */
     public function del(array|string $key, string ...$other_keys): void;
 
     public function ensureOpenConnection(): void;

Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,6 @@ public function wipeStorage(): void`
`56`	`56`	`$searchPattern = '';`
`57`	`57`
`58`	`58`	`$globalPrefix = $this->redis->getOption(RedisClient::OPT_PREFIX);`
`59`		`- // @phpstan-ignore-next-line false positive, phpstan thinks getOptions returns int`
`60`	`59`	`if (is_string($globalPrefix)) {`
`61`	`60`	`$searchPattern .= $globalPrefix;`
`62`	`61`	`}`
`@@ -183,15 +182,15 @@ public function updateSummary(array $data): void`
`183`	`182`	`if ($json === false) {`
`184`	`183`	`throw new RuntimeException(json_last_error_msg());`
`185`	`184`	`}`
`186`		`- $this->redis->setNx($metaKey, $json); /** @phpstan-ignore-line */`
	`185`	`+ $this->redis->setNx($metaKey, $json);`
`187`	`186`
`188`	`187`	`// store value key`
`189`	`188`	`$valueKey = $summaryKey.':'.$this->valueKey($data);`
`190`	`189`	`$json = json_encode($this->encodeLabelValues($data['labelValues']));`
`191`	`190`	`if ($json === false) {`
`192`	`191`	`throw new RuntimeException(json_last_error_msg());`
`193`	`192`	`}`
`194`		`- $this->redis->setNx($valueKey, $json); /** @phpstan-ignore-line */`
	`193`	`+ $this->redis->setNx($valueKey, $json);`
`195`	`194`
`196`	`195`	`// trick to handle uniqid collision`
`197`	`196`	`$done = false;`
`@@ -370,12 +369,10 @@ protected function collectHistograms(): array`
`370`	`369`
`371`	`370`	`protected function removePrefixFromKey(string $key): string`
`372`	`371`	`{`
`373`		`- // @phpstan-ignore-next-line false positive, phpstan thinks getOptions returns int`
`374`	`372`	`if ($this->redis->getOption(RedisClient::OPT_PREFIX) === null) {`
`375`	`373`	`return $key;`
`376`	`374`	`}`
`377`	`375`
`378`		`- // @phpstan-ignore-next-line false positive, phpstan thinks getOptions returns int`
`379`	`376`	`return substr($key, strlen($this->redis->getOption(RedisClient::OPT_PREFIX)));`
`380`	`377`	`}`
`381`	`378`
Original file line number	Diff line number	Diff line change
`@@ -45,6 +45,7 @@ class Predis extends AbstractRedis`
`45`	`45`	`/**`
`46`	`46`	`* Redis constructor.`
`47`	`47`	`*`
	`48`	`+ * @param mixed[] $parameters`
`48`	`49`	`* @param mixed[] $options`
`49`	`50`	`*/`
`50`	`51`	`public function __construct(array $parameters = [], array $options = [])`
`@@ -71,7 +72,7 @@ public static function fromExistingConnection(Client $client): self`
`71`	`72`	`];`
`72`	`73`
`73`	`74`	`$self = new self;`
`74`		`- $self->redis = new PredisClient($client, self::$defaultParameters, $allOptions);`
	`75`	`+ $self->redis = new PredisClient($client, $allOptions);`
`75`	`76`
`76`	`77`	`return $self;`
`77`	`78`	`}`
Original file line number	Diff line number	Diff line change
`@@ -13,19 +13,28 @@ class PHPRedis implements RedisClient`
`13`	`13`	`*/`
`14`	`14`	`private $redis;`
`15`	`15`
	`16`	`+ /**`
	`17`	`+ * @var mixed[]`
	`18`	`+ */`
`16`	`19`	`private $options = [];`
`17`	`20`
`18`	`21`	`/**`
`19`	`22`	`* @var bool`
`20`	`23`	`*/`
`21`	`24`	`private $connectionInitialized = false;`
`22`	`25`
	`26`	`+ /**`
	`27`	`+ * @param mixed[] $options`
	`28`	`+ */`
`23`	`29`	`public function __construct(\Redis $redis, array $options)`
`24`	`30`	`{`
`25`	`31`	`$this->redis = $redis;`
`26`	`32`	`$this->options = $options;`
`27`	`33`	`}`
`28`	`34`
	`35`	`+ /**`
	`36`	`+ * @param mixed[] $options`
	`37`	`+ */`
`29`	`38`	`public static function create(array $options): self`
`30`	`39`	`{`
`31`	`40`	`$redis = new \Redis;`
`@@ -43,22 +52,22 @@ public function eval(string $script, array $args = [], int $num_keys = 0): void`
`43`	`52`	`$this->redis->eval($script, $args, $num_keys);`
`44`	`53`	`}`
`45`	`54`
`46`		`- public function set(string $key, mixed $value, mixed $options = null): void`
	`55`	`+ public function set(string $key, mixed $value, mixed $options = null): bool`
`47`	`56`	`{`
`48`		`- $this->redis->set($key, $value, $options);`
	`57`	`+ return $this->redis->set($key, $value, $options);`
`49`	`58`	`}`
`50`	`59`
`51`	`60`	`public function setNx(string $key, mixed $value): void`
`52`	`61`	`{`
`53`		`- $this->redis->setNx($key, $value);`
	`62`	`+ $this->redis->setNx($key, $value); /** @phpstan-ignore-line */`
`54`	`63`	`}`
`55`	`64`
`56`	`65`	`public function hSetNx(string $key, string $field, mixed $value): bool`
`57`	`66`	`{`
`58`	`67`	`return $this->redis->hSetNx($key, $field, $value);`
`59`	`68`	`}`
`60`	`69`
`61`		`- public function sMembers(string $key): array\|false`
	`70`	`+ public function sMembers(string $key): array`
`62`	`71`	`{`
`63`	`72`	`return $this->redis->sMembers($key);`
`64`	`73`	`}`
Original file line number	Diff line number	Diff line change
`@@ -12,17 +12,30 @@ class Predis implements RedisClient`
`12`	`12`	`RedisClient::OPT_PREFIX => 'prefix',`
`13`	`13`	`];`
`14`	`14`
	`15`	`+ /**`
	`16`	`+ * @var Client`
	`17`	`+ */`
`15`	`18`	`private $client;`
`16`	`19`
	`20`	`+ /**`
	`21`	`+ * @var mixed[]`
	`22`	`+ */`
`17`	`23`	`private $options = [];`
`18`	`24`
	`25`	`+ /**`
	`26`	`+ * @param mixed[] $options`
	`27`	`+ */`
`19`	`28`	`public function __construct(Client $redis, array $options)`
`20`	`29`	`{`
`21`	`30`	`$this->client = $redis;`
`22`	`31`
`23`	`32`	`$this->options = $options;`
`24`	`33`	`}`
`25`	`34`
	`35`	`+ /**`
	`36`	`+ * @param mixed[] $parameters`
	`37`	`+ * @param mixed[] $options`
	`38`	`+ */`
`26`	`39`	`public static function create(array $parameters, array $options): self`
`27`	`40`	`{`
`28`	`41`	`$redisClient = new Client($parameters, $options);`
`@@ -46,11 +59,17 @@ public function eval(string $script, array $args = [], int $num_keys = 0): void`
`46`	`59`	`$this->client->eval($script, $num_keys, ...$args);`
`47`	`60`	`}`
`48`	`61`
`49`		`- public function set(string $key, mixed $value, mixed $options = null): void`
	`62`	`+ public function set(string $key, mixed $value, mixed $options = null): bool`
`50`	`63`	`{`
`51`		`- $this->client->set($key, $value, ...$this->flattenFlags($options));`
	`64`	`+ $result = $this->client->set($key, $value, ...$this->flattenFlags($options));`
	`65`	`+`
	`66`	`+ return (string) $result === 'OK';`
`52`	`67`	`}`
`53`	`68`
	`69`	`+ /**`
	`70`	`+ * @param array<int\|string, mixed> $flags`
	`71`	`+ * @return mixed[]`
	`72`	`+ */`
`54`	`73`	`private function flattenFlags(array $flags): array`
`55`	`74`	`{`
`56`	`75`	`$result = [];`
`@@ -73,10 +92,10 @@ public function setNx(string $key, mixed $value): void`
`73`	`92`
`74`	`93`	`public function hSetNx(string $key, string $field, mixed $value): bool`
`75`	`94`	`{`
`76`		`- return $this->hsetnx($key, $field, $value);`
	`95`	`+ return $this->hSetNx($key, $field, $value);`
`77`	`96`	`}`
`78`	`97`
`79`		`- public function sMembers(string $key): array\|false`
	`98`	`+ public function sMembers(string $key): array`
`80`	`99`	`{`
`81`	`100`	`return $this->client->smembers($key);`
`82`	`101`	`}`