feat: add PHPStan dynamic throw type extensions for brick/math and brick/money

Monorepo with two independent Composer packages:
- simpod/phpstan-brick-math: narrows throw types for BigNumber factory,
  conversion, operation, and rounding-mode methods
- simpod/phpstan-brick-money: narrows throw types for Money/RationalMoney
  factory, arithmetic, comparison, conversion, and CurrencyConverter methods

Extracted from brick/math#112 and brick/money#116.

Author: simPod

.github/workflows/coding-standards.yml

@@ -0,0 +1,40 @@
+name: "Coding Standards"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - "main"
+
+jobs:
+  coding-standards:
+    name: "Coding Standards - ${{ matrix.package }}"
+    runs-on: "ubuntu-24.04"
+
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - "math"
+          - "money"
+
+    defaults:
+      run:
+        working-directory: "${{ matrix.package }}"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v6"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.4"
+          tools: "cs2pr"
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v2"
+
+      - name: "Run PHP_CodeSniffer"
+        run: "vendor/bin/phpcs -q --no-colors --report=checkstyle | cs2pr"

.github/workflows/static-analysis.yml

@@ -0,0 +1,40 @@
+name: "Static Analysis"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - "main"
+
+jobs:
+  static-analysis-phpstan:
+    name: "PHPStan - ${{ matrix.package }}"
+    runs-on: "ubuntu-24.04"
+
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - "math"
+          - "money"
+
+    defaults:
+      run:
+        working-directory: "${{ matrix.package }}"
+
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v6"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.4"
+          tools: "cs2pr"
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v2"
+
+      - name: "Run a static analysis with phpstan/phpstan"
+        run: "vendor/bin/phpstan analyse --error-format=checkstyle | cs2pr"

.gitignore

@@ -0,0 +1,4 @@
+/math/vendor/
+/math/composer.lock
+/money/vendor/
+/money/composer.lock

math/composer.json

@@ -0,0 +1,23 @@
+{
+    "name": "simpod/phpstan-brick-math",
+    "description": "PHPStan dynamic throw type extensions for brick/math",
+    "license": "MIT",
+    "type": "phpstan-extension",
+    "require": {
+        "php": "^8.4",
+        "brick/math": "^0.15",
+        "phpstan/phpstan": "^2.1"
+    },
+    "extra": {
+        "phpstan": {
+            "includes": [
+                "extension.neon"
+            ]
+        }
+    },
+    "autoload": {
+        "psr-4": {
+            "Brick\\Math\\PHPStan\\": "src/"
+        }
+    }
+}

math/extension.neon

@@ -0,0 +1,20 @@
+services:
+	-
+		class: Brick\Math\PHPStan\BigNumberOfThrowTypeExtension
+		tags:
+			- phpstan.dynamicStaticMethodThrowTypeExtension
+
+	-
+		class: Brick\Math\PHPStan\BigNumberConversionThrowTypeExtension
+		tags:
+			- phpstan.dynamicMethodThrowTypeExtension
+
+	-
+		class: Brick\Math\PHPStan\BigNumberOperationThrowTypeExtension
+		tags:
+			- phpstan.dynamicMethodThrowTypeExtension
+
+	-
+		class: Brick\Math\PHPStan\RoundingModeThrowTypeExtension
+		tags:
+			- phpstan.dynamicMethodThrowTypeExtension

math/phpstan.neon

@@ -0,0 +1,7 @@
+includes:
+    - extension.neon
+
+parameters:
+    level: 10
+    paths:
+        - src

math/src/BigNumberConversionThrowTypeExtension.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\Math\PHPStan;
+
+use Brick\Math\BigDecimal;
+use Brick\Math\BigInteger;
+use Brick\Math\BigNumber;
+use Brick\Math\BigRational;
+use Brick\Math\Exception\IntegerOverflowException;
+use Brick\Math\Exception\RoundingNecessaryException;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodThrowTypeExtension;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\Type;
+
+/**
+ * Narrows the throw type of toBigInteger(), toBigDecimal(), toBigRational(), and toInt().
+ *
+ * When the caller is already the target type, toBigInteger/toBigDecimal/toBigRational are no-ops and cannot throw.
+ * When toInt() is called on {@see BigInteger}, only {@see IntegerOverflowException} can be thrown
+ * (no {@see RoundingNecessaryException}).
+ */
+final class BigNumberConversionThrowTypeExtension implements DynamicMethodThrowTypeExtension
+{
+    private const METHOD_TO_CLASS = [
+        'toBigInteger' => BigInteger::class,
+        'toBigDecimal' => BigDecimal::class,
+        'toBigRational' => BigRational::class,
+    ];
+
+    public function isMethodSupported(MethodReflection $methodReflection): bool
+    {
+        $className = $methodReflection->getDeclaringClass()->getName();
+        $isBigNumber = $className === BigNumber::class
+            || $methodReflection->getDeclaringClass()->isSubclassOf(BigNumber::class);
+
+        if (! $isBigNumber) {
+            return false;
+        }
+
+        return isset(self::METHOD_TO_CLASS[$methodReflection->getName()])
+            || $methodReflection->getName() === 'toInt';
+    }
+
+    public function getThrowTypeFromMethodCall(
+        MethodReflection $methodReflection,
+        MethodCall $methodCall,
+        Scope $scope,
+    ): ?Type {
+        $callerType = $scope->getType($methodCall->var);
+        $methodName = $methodReflection->getName();
+
+        if ($methodName === 'toInt') {
+            // BigInteger::toInt() can only throw IntegerOverflowException (no RoundingNecessaryException).
+            if ((new ObjectType(BigInteger::class))->isSuperTypeOf($callerType)->yes()) {
+                return new ObjectType(IntegerOverflowException::class);
+            }
+
+            return $methodReflection->getThrowType();
+        }
+
+        $targetClass = self::METHOD_TO_CLASS[$methodName];
+
+        if ((new ObjectType($targetClass))->isSuperTypeOf($callerType)->yes()) {
+            return null;
+        }
+
+        return $methodReflection->getThrowType();
+    }
+}