feat: deprecate non-int values in Counter::set() (#17)

* feat: deprecate non-int values in Counter::set()

Passing a non-int value to Counter::set() now triggers an
E_USER_DEPRECATED notice before the existing InvalidArgumentException is
thrown. The parameter type will be narrowed to int in the next major
release. Documents the value as int<0, max>.

Closes #16

* refactor: remove redundant inline phpcs ignore in Counter::set()

The TriggerErrorSeeUrlFormat sniff is now excluded globally in
phpcs.xml, so the inline phpcs:ignore is no longer needed.

Author: kimpepper

src/Counter.php

@@ -24,15 +24,19 @@ public function getType(): string {
   /**
    * Adds a value for this metric.
    *
-   * @param mixed $value
-   *   The value.
+   * @param int<0, max> $value
+   *   The value. Non-int values are deprecated.
    * @param array<string, string|int|float> $labels
    *   The list of key value label pairs.
    *
    * @throws \InvalidArgumentException
    *   If the value is not a non-negative integer.
    */
   public function set(mixed $value, array $labels = []): void {
+    // @phpstan-ignore function.alreadyNarrowedType
+    if (!is_int($value)) {
+      @trigger_error(sprintf('Passing a non-int 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/16', __METHOD__), E_USER_DEPRECATED);
+    }
     if (!$this->isValidValue($value)) {
       throw new \InvalidArgumentException("A count value must be a positive integer.");
     }

tests/Unit/CounterTest.php

@@ -5,6 +5,7 @@
 namespace PNX\Prometheus\Tests\Unit;
 
 use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\IgnoreDeprecations;
 use PHPUnit\Framework\TestCase;
 use PNX\Prometheus\Counter;
 
@@ -18,18 +19,52 @@ class CounterTest extends TestCase {
    * Tests setting counter values.
    */
   public function testCounter(): void {
-
     $counter = new Counter('foo', 'bar', 'Example counter help');
     $counter->set(89, ['baz' => 'wiz']);
 
     $this->assertEquals("foo_bar", $counter->getName());
     $this->assertEquals("counter", $counter->getType());
 
+    $values = $counter->getLabelledValues();
+    $this->assertCount(1, $values);
+    $this->assertEquals(89, $values[0]->getValue());
+  }
+
+  /**
+   * Tests that a negative value throws an exception.
+   */
+  public function testNegativeValueThrows(): void {
+    $counter = new Counter('foo', 'bar', 'Example counter help');
     $this->expectException(\InvalidArgumentException::class);
+    // @phpstan-ignore argument.type
     $counter->set(-1, ['baz' => 'wiz']);
+  }
+
+  /**
+   * Tests that a non-int value triggers a deprecation notice.
+   */
+  public function testNonIntValueIsDeprecated(): void {
+    $counter = new Counter('foo', 'bar', 'Example counter help');
+    $this->expectUserDeprecationMessage('Passing a non-int value to PNX\Prometheus\Counter::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/16');
+
+    try {
+      // @phpstan-ignore argument.type
+      $counter->set('bing', ['baz' => 'wiz']);
+    }
+    catch (\InvalidArgumentException) {
+      // The deprecation is triggered before the exception is thrown.
+    }
+  }
 
+  /**
+   * Tests that a non-int value still throws an exception.
+   */
+  #[IgnoreDeprecations]
+  public function testNonIntValueThrows(): void {
+    $counter = new Counter('foo', 'bar', 'Example counter help');
     $this->expectException(\InvalidArgumentException::class);
-    $counter->set('bing', ['baz' => 'wiz']);
+    // @phpstan-ignore argument.type
+    @$counter->set('bing', ['baz' => 'wiz']);
   }
 
   /**