Type current_url() and previous_url() url helpers

Author: paulbalandan

docs/type-inference.md

@@ -52,6 +52,14 @@ This extension provides the precise return type for the `fake()` function, typin
 record of the given model's return type (an entity, a shaped array, or a `stdClass`). The model may be passed
 as a class string, a model name, or a model instance.
 
+### UrlHelperFunctionReturnTypeExtension
+
+**Class:** `CodeIgniter\PHPStan\Type\UrlHelperFunctionReturnTypeExtension`
+
+This extension resolves the `string|URI` url helpers `current_url()` and `previous_url()` from their
+constant `$returnObject` flag: a constant `true` returns a `CodeIgniter\HTTP\URI`, while `false` or an
+absent flag returns a `string`. A non-constant flag leaves the declared union in place.
+
 ## Dynamic Method Return Type Extensions
 
 ### ReflectionHelperMethodInvokerStaticReturnTypeExtension

extension.neon

@@ -128,6 +128,11 @@ services:
     tags:
       - phpstan.broker.dynamicFunctionReturnTypeExtension
 
+  -
+    class: CodeIgniter\PHPStan\Type\UrlHelperFunctionReturnTypeExtension
+    tags:
+      - phpstan.broker.dynamicFunctionReturnTypeExtension
+
   -
     class: CodeIgniter\PHPStan\Type\SuperglobalsMethodDynamicReturnTypeExtension
     tags:

src/Type/UrlHelperFunctionReturnTypeExtension.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\PHPStan\Type;
+
+use CodeIgniter\HTTP\URI;
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\Constant\ConstantBooleanType;
+use PHPStan\Type\DynamicFunctionReturnTypeExtension;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\StringType;
+use PHPStan\Type\Type;
+
+/**
+ * Resolves the `string|URI` url helpers `current_url()` and `previous_url()` from the constant
+ * `$returnObject` flag: `true` returns a `URI`, `false` or absent a `string`.
+ */
+final class UrlHelperFunctionReturnTypeExtension implements DynamicFunctionReturnTypeExtension
+{
+    private const SUPPORTED_FUNCTIONS = ['current_url', 'previous_url'];
+
+    public function isFunctionSupported(FunctionReflection $functionReflection): bool
+    {
+        return in_array($functionReflection->getName(), self::SUPPORTED_FUNCTIONS, true);
+    }
+
+    public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): ?Type
+    {
+        $args = $functionCall->getArgs();
+
+        $returnObject = isset($args[0])
+            ? $scope->getType($args[0]->value)
+            : new ConstantBooleanType(false);
+
+        if ($returnObject->isTrue()->yes()) {
+            return new ObjectType(URI::class);
+        }
+
+        if ($returnObject->isFalse()->yes()) {
+            return new StringType();
+        }
+
+        return null;
+    }
+}

tests/data/type-inference/url-helper-functions.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\PHPStan\Tests\Type;
+
+use function PHPStan\Testing\assertType;
+
+function test_url_helper_functions(bool $flag): void
+{
+    // A false or absent flag returns a string, a constant true returns a URI.
+    assertType('string', current_url());
+    assertType('string', current_url(false));
+    assertType('CodeIgniter\HTTP\URI', current_url(true));
+
+    assertType('string', previous_url());
+    assertType('string', previous_url(false));
+    assertType('CodeIgniter\HTTP\URI', previous_url(true));
+
+    // A non-constant flag leaves the declared union.
+    assertType('CodeIgniter\HTTP\URI|string', current_url($flag));
+    assertType('CodeIgniter\HTTP\URI|string', previous_url($flag));
+}