Add dynamic function return extension for service and single_service

Author: paulbalandan

README.md

@@ -10,6 +10,7 @@
 This extension provides the following features:
 
 * Provides precise return types for `config()` and `model()` functions.
+* Provides precise return types for `service()` and `single_service()` functions.
 * Checks if the string argument passed to `config()` or `model()` function is a valid class string extending `CodeIgniter\Config\BaseConfig` or `CodeIgniter\Model`, respectively. This can be turned off by setting `codeigniter.checkArgumentTypeOfFactories: false` in your `phpstan.neon`.
 * Disallows instantiating cache handlers using `new` and suggests to use the `CacheFactory` class instead.
 
@@ -51,3 +52,12 @@ parameters:
       - Acme\Blog\Models\
 
 ```
+
+For the `service()` and `single_service()` functions, you can declare your own service implementation classes.
+
+```yml
+parameters:
+  codeigniter:
+    additionalServices:
+      - Acme\Blog\Config\ServiceFactory
+```

extension.neon

@@ -8,12 +8,14 @@ parameters:
   codeigniter:
     additionalConfigNamespaces: []
     additionalModelNamespaces: []
+    additionalServices: []
     checkArgumentTypeOfFactories: true
 
 parametersSchema:
   codeigniter: structure([
     additionalConfigNamespaces: listOf(string())
     additionalModelNamespaces: listOf(string())
+    additionalServices: listOf(string())
     checkArgumentTypeOfFactories: bool()
   ])
 
@@ -24,11 +26,21 @@ services:
       additionalConfigNamespaces: %codeigniter.additionalConfigNamespaces%
       additionalModelNamespaces: %codeigniter.additionalModelNamespaces%
 
+  servicesReturnTypeHelper:
+    class: CodeIgniter\PHPStan\Type\ServicesReturnTypeHelper
+    arguments:
+      additionalServices: %codeigniter.additionalServices%
+
   -
     class: CodeIgniter\PHPStan\Type\FactoriesFunctionReturnTypeExtension
     tags:
       - phpstan.broker.dynamicFunctionReturnTypeExtension
 
+  -
+    class: CodeIgniter\PHPStan\Type\ServicesFunctionReturnTypeExtension
+    tags:
+      - phpstan.broker.dynamicFunctionReturnTypeExtension
+
   -
     class: CodeIgniter\PHPStan\Rules\Functions\FactoriesFunctionArgumentTypeRule
 

src/Type/ServicesFunctionReturnTypeExtension.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\PHPStan\Type;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\DynamicFunctionReturnTypeExtension;
+use PHPStan\Type\Type;
+
+final class ServicesFunctionReturnTypeExtension implements DynamicFunctionReturnTypeExtension
+{
+    public function __construct(
+        private readonly ServicesReturnTypeHelper $servicesReturnTypeHelper
+    ) {}
+
+    public function isFunctionSupported(FunctionReflection $functionReflection): bool
+    {
+        return in_array($functionReflection->getName(), ['service', 'single_service'], true);
+    }
+
+    public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): ?Type
+    {
+        $arguments = $functionCall->getArgs();
+
+        if ($arguments === []) {
+            return null;
+        }
+
+        return $this->servicesReturnTypeHelper->check($scope->getType($arguments[0]->value), $scope);
+    }
+}

src/Type/ServicesReturnTypeHelper.php

@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * 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\Config\Services as FrameworkServices;
+use Config\Services as AppServices;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\ClassReflection;
+use PHPStan\Reflection\ParametersAcceptorSelector;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\ShouldNotHappenException;
+use PHPStan\Type\IntersectionType;
+use PHPStan\Type\NullType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeTraverser;
+use PHPStan\Type\UnionType;
+
+final class ServicesReturnTypeHelper
+{
+    /**
+     * @var array<int, string>
+     */
+    private const IMPOSSIBLE_SERVICE_METHOD_NAMES = [
+        '__callStatic',
+        'buildServicesCache',
+        'createRequest',
+        'discoverServices',
+        'getSharedInstance',
+        'injectMock',
+        'reset',
+        'resetSingle',
+        'serviceExists',
+    ];
+
+    /**
+     * @var array<int, class-string>
+     */
+    private array $services;
+
+    /**
+     * @var array<int, ClassReflection>
+     */
+    private static array $servicesReflection = [];
+
+    /**
+     * @param array<int, class-string> $additionalServices
+     */
+    public function __construct(
+        private readonly ReflectionProvider $reflectionProvider,
+        array $additionalServices
+    ) {
+        $this->services = [
+            FrameworkServices::class,
+            AppServices::class,
+            ...$additionalServices,
+        ];
+    }
+
+    public function check(Type $type, Scope $scope): Type
+    {
+        if (self::$servicesReflection === []) {
+            self::$servicesReflection = array_map(function (string $service): ClassReflection {
+                if (! $this->reflectionProvider->hasClass($service)) {
+                    throw new ShouldNotHappenException(sprintf('Service class "%s" is not found.', $service));
+                }
+
+                return $this->reflectionProvider->getClass($service);
+            }, $this->services);
+        }
+
+        return TypeTraverser::map($type, static function (Type $type, callable $traverse) use ($scope): Type {
+            if ($type instanceof UnionType || $type instanceof IntersectionType) {
+                return $traverse($type);
+            }
+
+            $constantStrings = $type->getConstantStrings();
+
+            if ($constantStrings === []) {
+                return new NullType();
+            }
+
+            $constantString = current($constantStrings)->getValue();
+
+            foreach (self::IMPOSSIBLE_SERVICE_METHOD_NAMES as $impossibleServiceMethodName) {
+                if (strtolower($constantString) === strtolower($impossibleServiceMethodName)) {
+                    return new NullType();
+                }
+            }
+
+            $methodReflection = null;
+
+            foreach (self::$servicesReflection as $servicesReflection) {
+                if ($servicesReflection->hasMethod($constantString)) {
+                    $methodReflection = $servicesReflection->getMethod($constantString, $scope);
+                }
+            }
+
+            if ($methodReflection === null) {
+                return new NullType();
+            }
+
+            if (! $methodReflection->isStatic() || ! $methodReflection->isPublic()) {
+                return new NullType();
+            }
+
+            return ParametersAcceptorSelector::selectSingle($methodReflection->getVariants())->getReturnType();
+        });
+    }
+}

tests/Fixtures/Type/OtherServices.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\PHPStan\Tests\Fixtures\Type;
+
+use Closure;
+use CodeIgniter\Config\BaseService;
+use stdClass;
+
+final class OtherServices extends BaseService
+{
+    /**
+     * This should overwrite native migrations.
+     */
+    public static function migrations(): stdClass
+    {
+        return new stdClass();
+    }
+
+    public static function invoker(string $callable): Closure
+    {
+        return Closure::fromCallable($callable);
+    }
+}

tests/Fixtures/Type/services.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 2023 CodeIgniter Foundation <admin@codeigniter.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+use CodeIgniter\Autoloader\Autoloader;
+use CodeIgniter\Autoloader\FileLocator;
+use CodeIgniter\Cache\CacheInterface;
+use CodeIgniter\CLI\Commands;
+use CodeIgniter\Debug\Exceptions;
+use CodeIgniter\Debug\Iterator;
+use CodeIgniter\Debug\Toolbar;
+use CodeIgniter\Email\Email;
+use CodeIgniter\Filters\Filters;
+use CodeIgniter\HTTP\CLIRequest;
+use CodeIgniter\HTTP\ResponseInterface;
+use CodeIgniter\Log\Logger;
+use CodeIgniter\Pager\Pager;
+use CodeIgniter\Validation\ValidationInterface;
+use CodeIgniter\View\Cell;
+use CodeIgniter\View\Parser;
+use CodeIgniter\View\View;
+
+use function PHPStan\Testing\assertType;
+
+// from CodeIgniter\Config\Services
+assertType(CacheInterface::class, service('cache'));
+assertType(Commands::class, service('commands'));
+assertType(CLIRequest::class, single_service('clirequest'));
+assertType(Email::class, service('email'));
+assertType(Exceptions::class, single_service('exceptions'));
+assertType(Filters::class, service('filters'));
+assertType(Iterator::class, service('iterator'));
+assertType(Logger::class, single_service('logger'));
+assertType(Pager::class, service('pager'));
+assertType(Parser::class, service('parser'));
+assertType(View::class, service('renderer'));
+assertType('CodeIgniter\HTTP\CLIRequest|CodeIgniter\HTTP\IncomingRequest', service('request'));
+assertType(ResponseInterface::class, service('response'));
+assertType(Toolbar::class, service('toolbar'));
+assertType(ValidationInterface::class, service('validation'));
+assertType(Cell::class, service('viewcell'));
+assertType('null', service('createRequest'));
+
+// from CodeIgniter\Config\BaseService
+assertType(Autoloader::class, single_service('autoloader'));
+assertType(FileLocator::class, service('locator'));
+assertType('null', service('__callStatic'));
+assertType('null', service('serviceExists'));
+assertType('null', service('reset'));
+assertType('null', service('resetSingle'));
+assertType('null', service('injectMock'));
+
+// from OtherServices
+// this should be overridden by OtherServices
+assertType(stdClass::class, service('migrations'));
+assertType(Closure::class, service('invoker'));

tests/Type/DynamicFunctionReturnTypeExtensionTest.php

@@ -34,6 +34,8 @@ public static function provideFileAssertsCases(): iterable
         yield from self::gatherAssertTypes(__DIR__ . '/../Fixtures/Type/config.php');
 
         yield from self::gatherAssertTypes(__DIR__ . '/../Fixtures/Type/model.php');
+
+        yield from self::gatherAssertTypes(__DIR__ . '/../Fixtures/Type/services.php');
     }
 
     public static function getAdditionalConfigFiles(): array

tests/extension-test.neon

@@ -4,3 +4,5 @@ parameters:
   codeigniter:
     additionalModelNamespaces:
       - CodeIgniter\PHPStan\Tests\Fixtures\Type
+    additionalServices:
+      - CodeIgniter\PHPStan\Tests\Fixtures\Type\OtherServices