Add json decode return type extension

phpstan-safe-rule.neon

@@ -23,3 +23,7 @@ services:
     class: TheCodingMachine\Safe\PHPStan\Type\Php\PregMatchTypeSpecifyingExtension
     tags:
       - phpstan.typeSpecifier.functionTypeSpecifyingExtension
+  -
+      class: TheCodingMachine\Safe\PHPStan\Type\Php\JsonDecodeDynamicReturnTypeExtension
+      tags:
+        - phpstan.broker.dynamicFunctionReturnTypeExtension

phpstan.neon

@@ -25,5 +25,10 @@ parameters:
             identifier: phpstanApi.interface
             count: 1
             path: src/Rules/Error/SafeRuleError.php
+        -
+            message: '#^Calling PHPStan\\Type\\Php\\JsonThrowOnErrorDynamicReturnTypeExtension\:\:getTypeFromFunctionCall\(\) is not covered by backward compatibility promise\. The method might change in a minor PHPStan version\.$#'
+            identifier: phpstanApi.method
+            count: 1
+            path: src/Type/Php/JsonDecodeDynamicReturnTypeExtension.php
 includes:
     - phpstan-safe-rule.neon

src/Type/Php/JsonDecodeDynamicReturnTypeExtension.php

@@ -0,0 +1,46 @@
+<?php declare(strict_types=1);
+
+
+namespace TheCodingMachine\Safe\PHPStan\Type\Php;
+
+use PhpParser\Node\Expr\FuncCall;
+use PhpParser\Node\Name;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Type\DynamicFunctionReturnTypeExtension;
+use PHPStan\Type\NeverType;
+use PHPStan\Type\Php\JsonThrowOnErrorDynamicReturnTypeExtension;
+use PHPStan\Type\Type;
+
+/**
+ * @see \PHPStan\Type\Php\JsonThrowOnErrorDynamicReturnTypeExtension
+ */
+final class JsonDecodeDynamicReturnTypeExtension implements DynamicFunctionReturnTypeExtension
+{
+    private FunctionReflection $nativeJsonDecodeReflection;
+
+    public function __construct(
+        private readonly JsonThrowOnErrorDynamicReturnTypeExtension $phpstanCheck,
+        ReflectionProvider $reflectionProvider,
+    ) {
+        $this->nativeJsonDecodeReflection = $reflectionProvider->getFunction(new Name('json_decode'), null);
+    }
+
+    public function isFunctionSupported(FunctionReflection $functionReflection): bool
+    {
+        return strtolower($functionReflection->getName()) === 'safe\json_decode';
+    }
+
+    public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): Type
+    {
+        $result = $this->phpstanCheck->getTypeFromFunctionCall($this->nativeJsonDecodeReflection, $functionCall, $scope);
+
+        // if PHPStan reports null and there is a json error, then an invalid constant string was passed
+        if ($result->isNull()->yes() && JSON_ERROR_NONE !== json_last_error()) {
+            return new NeverType();
+        }
+
+        return $result;
+    }
+}

tests/Type/Php/TypeAssertionsTest.php

@@ -14,6 +14,7 @@ public static function dataFileAsserts(): iterable
         yield from self::gatherAssertTypes(__DIR__ . '/data/preg_match_unchecked.php');
         yield from self::gatherAssertTypes(__DIR__ . '/data/preg_match_checked.php');
         yield from self::gatherAssertTypes(__DIR__ . '/data/preg_replace_return.php');
+        yield from self::gatherAssertTypes(__DIR__ . '/data/json_decode_return.php');
     }
 
     /**

tests/Type/Php/data/json_decode_return.php

@@ -0,0 +1,35 @@
+<?php
+$value = \Safe\json_decode('null');
+\PHPStan\Testing\assertType('null', $value);
+
+$value = \Safe\json_decode('false');
+\PHPStan\Testing\assertType('false', $value);
+
+$value = \Safe\json_decode('[]');
+\PHPStan\Testing\assertType('array{}', $value);
+
+$value = \Safe\json_decode('{}');
+\PHPStan\Testing\assertType('stdClass', $value);
+
+$value = \Safe\json_decode('{}', true);
+\PHPStan\Testing\assertType('array{}', $value);
+
+$value = \Safe\json_decode('{}', flags: JSON_OBJECT_AS_ARRAY);
+\PHPStan\Testing\assertType('array{}', $value);
+
+$value = \Safe\json_decode('{"foo": "bar"}');
+\PHPStan\Testing\assertType('stdClass', $value);
+
+$value = \Safe\json_decode('{"foo": "bar"}', true);
+\PHPStan\Testing\assertType("array{foo: 'bar'}", $value);
+
+$value = \Safe\json_decode('{', true);
+\PHPStan\Testing\assertType('*NEVER*', $value);
+
+function(string $json): void {
+    $value = \Safe\json_decode($json);
+    \PHPStan\Testing\assertType('mixed', $value);
+
+    $value = \Safe\json_decode($json, true);
+    \PHPStan\Testing\assertType('mixed~object', $value);
+};

tests/Type/Php/data/preg_match_unchecked.php

@@ -7,7 +7,7 @@
 $string = 'Hello World';
 
 // when return value isn't checked, we may-or-may-not have matches
-$type = "array{0?: string, 1?: non-empty-string, 2?: 'o', 3?: 'World'}";
+$type = "list{0?: string, 1?: non-empty-string, 2?: 'o', 3?: 'World'}";
 
 // @phpstan-ignore-next-line - use of unsafe is intentional
 \preg_match($pattern, $string, $matches);