feat: deprecate non-int/float values in Gauge::set() (#15)

* feat: deprecate non-int/float values in Gauge::set()

Passing a value that is not an int or float to Gauge::set() now triggers
an E_USER_DEPRECATED notice. The value is still stored, so behaviour is
unchanged. The parameter type will be narrowed to int|float in the next
major release.

Also documents the encode() parameters in PrometheusEncoder so the
missing iterable value-type ignore is no longer needed.

Closes #14

* refactor: exclude Drupal See-url sniff in phpcs.xml

The TriggerErrorSeeUrlFormat sniff requires drupal.org URLs, which does
not apply to this GitHub project. Exclude it globally instead of using
an inline phpcs:ignore.

Author: kimpepper

phpcs.xml

@@ -4,5 +4,9 @@
   <file>./src</file>
   <file>./tests</file>
   <arg name="extensions" value="php"/>
-  <rule ref="Drupal"/>
+  <rule ref="Drupal">
+    <!-- Not a Drupal project: deprecation "See" links point to GitHub issues,
+         not drupal.org change records. -->
+    <exclude name="Drupal.Semantics.FunctionTriggerError.TriggerErrorSeeUrlFormat"/>
+  </rule>
 </ruleset>

src/Gauge.php

@@ -25,11 +25,14 @@ public function getType(): string {
    * Adds a value for this metric.
    *
    * @param mixed $value
-   *   The value.
+   *   The value. Non-int/float values are deprecated.
    * @param array<string, string|int|float> $labels
    *   The list of key value label pairs.
    */
   public function set(mixed $value, array $labels = []): void {
+    if (!is_int($value) && !is_float($value)) {
+      @trigger_error(sprintf('Passing a non-int/float value to %s() is deprecated in php_prometheus:1.1.0 and will throw a \TypeError in php_prometheus:2.0.0. See https://github.com/previousnext/php-prometheus/issues/14', __METHOD__), E_USER_DEPRECATED);
+    }
     $key = $this->getKey($labels);
     $this->labelledValues[$key] = new LabelledValue($this->getName(), $value, $labels);
   }

src/Serializer/PrometheusEncoder.php

@@ -23,7 +23,12 @@ public function supportsEncoding(string $format): bool {
   /**
    * {@inheritdoc}
    *
-   * @phpstan-ignore missingType.iterableValue
+   * @param mixed $data
+   *   The data to encode.
+   * @param string $format
+   *   The encoding format.
+   * @param array<string, mixed> $context
+   *   The serializer context.
    */
   public function encode(mixed $data, string $format, array $context = []): string {
     $output = [];

tests/Unit/GaugeTest.php

@@ -5,6 +5,8 @@
 namespace PNX\Prometheus\Tests\Unit;
 
 use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\IgnoreDeprecations;
 use PHPUnit\Framework\TestCase;
 use PNX\Prometheus\Gauge;
 
@@ -45,4 +47,56 @@ public function testGaugeNoValues(): void {
     $this->assertEmpty($gauge->getLabelledValues());
   }
 
+  /**
+   * Tests that int and float values are accepted without a deprecation notice.
+   */
+  #[DataProvider('numericValueProvider')]
+  public function testGaugeAcceptsNumericValue(int|float $value): void {
+    $gauge = new Gauge("foo", "bar", "A test gauge");
+    $gauge->set($value);
+
+    $values = $gauge->getLabelledValues();
+    $this->assertCount(1, $values);
+    $this->assertEquals($value, $values[0]->getValue());
+  }
+
+  /**
+   * Provides int and float values accepted by Gauge::set().
+   *
+   * @return array<string, array{int|float}>
+   *   The numeric values to test.
+   */
+  public static function numericValueProvider(): array {
+    return [
+      'integer' => [100],
+      'zero' => [0],
+      'negative integer' => [-5],
+      'float' => [1.5],
+      'negative float' => [-2.75],
+    ];
+  }
+
+  /**
+   * Tests that a non-int/float value triggers a deprecation notice.
+   */
+  public function testGaugeNonNumericValueIsDeprecated(): void {
+    $this->expectUserDeprecationMessage('Passing a non-int/float value to PNX\Prometheus\Gauge::set() is deprecated in php_prometheus:1.1.0 and will throw a \TypeError in php_prometheus:2.0.0. See https://github.com/previousnext/php-prometheus/issues/14');
+
+    $gauge = new Gauge("foo", "bar", "A test gauge");
+    $gauge->set("not-a-number");
+  }
+
+  /**
+   * Tests that a deprecated value is still stored.
+   */
+  #[IgnoreDeprecations]
+  public function testGaugeNonNumericValueIsStored(): void {
+    $gauge = new Gauge("foo", "bar", "A test gauge");
+    @$gauge->set("not-a-number");
+
+    $values = $gauge->getLabelledValues();
+    $this->assertCount(1, $values);
+    $this->assertEquals("not-a-number", $values[0]->getValue());
+  }
+
 }