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\\BitwiseFlagHelper::bitwiseOrContainsConstant\(\) 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,108 @@
+<?php declare(strict_types=1);
+
+
+namespace TheCodingMachine\Safe\PHPStan\Type\Php;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Reflection\ParametersAcceptorSelector;
+use PHPStan\Type\BitwiseFlagHelper;
+use PHPStan\Type\Constant\ConstantStringType;
+use PHPStan\Type\ConstantScalarType;
+use PHPStan\Type\ConstantTypeHelper;
+use PHPStan\Type\DynamicFunctionReturnTypeExtension;
+use PHPStan\Type\NeverType;
+use PHPStan\Type\ObjectWithoutClassType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use Safe\Exceptions\JsonException;
+
+/**
+ * @see \PHPStan\Type\Php\JsonThrowOnErrorDynamicReturnTypeExtension
+ */
+final class JsonDecodeDynamicReturnTypeExtension implements DynamicFunctionReturnTypeExtension
+{
+    public function __construct(
+        private readonly BitwiseFlagHelper $bitwiseFlagAnalyser,
+    ) {
+    }
+
+    public function isFunctionSupported(FunctionReflection $functionReflection): bool
+    {
+        return strtolower($functionReflection->getName()) === 'safe\json_decode';
+    }
+
+    public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): Type
+    {
+        $defaultReturnType = ParametersAcceptorSelector::selectFromArgs(
+            $scope,
+            $functionCall->getArgs(),
+            $functionReflection->getVariants(),
+        )->getReturnType();
+
+        return $this->narrowTypeForJsonDecode($functionCall, $scope, $defaultReturnType);
+    }
+
+    private function narrowTypeForJsonDecode(FuncCall $funcCall, Scope $scope, Type $fallbackType): Type
+    {
+        $args = $funcCall->getArgs();
+        $isForceArray = $this->isForceArray($funcCall, $scope);
+        if (!isset($args[0])) {
+            return $fallbackType;
+        }
+
+        $firstValueType = $scope->getType($args[0]->value);
+        if ([] !== $firstValueType->getConstantStrings()) {
+            $types = [];
+
+            foreach ($firstValueType->getConstantStrings() as $constantString) {
+                $types[] = $this->resolveConstantStringType($constantString, $isForceArray);
+            }
+
+            return TypeCombinator::union(...$types);
+        }
+
+        if ($isForceArray) {
+            return TypeCombinator::remove($fallbackType, new ObjectWithoutClassType());
+        }
+
+        return $fallbackType;
+    }
+
+    /**
+     * Is "json_decode(..., true)"?
+     */
+    private function isForceArray(FuncCall $funcCall, Scope $scope): bool
+    {
+        $args = $funcCall->getArgs();
+        if (!isset($args[1])) {
+            return false;
+        }
+
+        $secondArgType = $scope->getType($args[1]->value);
+        $secondArgValue = 1 === \count($secondArgType->getConstantScalarValues()) ? $secondArgType->getConstantScalarValues()[0] : null;
+
+        if (is_bool($secondArgValue)) {
+            return $secondArgValue;
+        }
+
+        if ($secondArgValue !== null || !isset($args[3])) {
+            return false;
+        }
+
+        // depends on used constants, @see https://www.php.net/manual/en/json.constants.php#constant.json-object-as-array
+        return $this->bitwiseFlagAnalyser->bitwiseOrContainsConstant($args[3]->value, $scope, 'JSON_OBJECT_AS_ARRAY')->yes();
+    }
+
+    private function resolveConstantStringType(ConstantStringType $constantStringType, bool $isForceArray): Type
+    {
+        try {
+            $decodedValue = \Safe\json_decode($constantStringType->getValue(), $isForceArray);
+        } catch (JsonException) {
+            return new NeverType();
+        }
+
+        return ConstantTypeHelper::getTypeFromValue($decodedValue);
+    }
+}

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,44 @@
+<?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);
+};
+
+function(string $json): void {
+    /** @var '{}'|'null' $json */
+    $value = \Safe\json_decode($json);
+    \PHPStan\Testing\assertType('stdClass|null', $value);
+
+    $value = \Safe\json_decode($json, true);
+    \PHPStan\Testing\assertType('array{}|null', $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);