feat: add Services::resetServicesCache() to reset services cache

phpstan.neon.dist

@@ -42,3 +42,6 @@ parameters:
 		booleansInConditions: true
 		disallowedConstructs: true
 		matchingInheritedMethodNames: true
+	codeigniter:
+		additionalServices:
+			- AfterAutoloadModule\Config\Services

system/Config/BaseService.php

@@ -388,6 +388,15 @@ public static function injectMock(string $name, $mock)
         static::$mocks[strtolower($name)] = $mock;
     }
 
+    /**
+     * Resets the service cache.
+     */
+    public static function resetServicesCache(): void
+    {
+        self::$serviceNames = [];
+        static::$discovered = false;
+    }
+
     protected static function buildServicesCache(): void
     {
         if (! static::$discovered) {

tests/_support/_AfterAutoloadModule/Config/Services.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace AfterAutoloadModule\Config;
+
+use AfterAutoloadModule\Test;
+use CodeIgniter\Config\BaseService;
+
+/**
+ * Services for testing BaseService::resetServicesCache().
+ *
+ * This class should not be discovered by the autoloader until the test adds
+ * this namespace to the autoloader.
+ */
+class Services extends BaseService
+{
+    /**
+     * Return a shared instance of the Test class for testing
+     */
+    public static function test(bool $getShared = true): Test
+    {
+        if ($getShared) {
+            return static::getSharedInstance('test');
+        }
+
+        return new Test();
+    }
+}

tests/_support/_AfterAutoloadModule/Test.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace AfterAutoloadModule;
+
+/**
+ * A simple class for testing BaseService::resetServicesCache().
+ *
+ * This class should not be discovered by the autoloader until the test adds
+ * this namespace to the autoloader.
+ */
+class Test
+{
+}

tests/system/CommonSingleServiceTest.php

@@ -110,6 +110,7 @@ public static function provideServiceNames(): iterable
             'serviceExists',
             'reset',
             'resetSingle',
+            'resetServicesCache',
             'injectMock',
             'encrypter', // Encrypter needs a starter key
             'session', // Headers already sent

tests/system/Config/ServicesTest.php

@@ -13,6 +13,7 @@
 
 namespace CodeIgniter\Config;
 
+use AfterAutoloadModule\Test;
 use CodeIgniter\Autoloader\Autoloader;
 use CodeIgniter\Autoloader\FileLocator;
 use CodeIgniter\Database\MigrationRunner;
@@ -350,6 +351,29 @@ public function testResetSingleCaseInsensitive(): void
         $this->assertNotInstanceOf(MockResponse::class, $someService);
     }
 
+    #[PreserveGlobalState(false)]
+    #[RunInSeparateProcess]
+    public function testResetServiceCache(): void
+    {
+        Services::injectMock('response', new MockResponse(new App()));
+        $response = service('response');
+        $this->assertInstanceOf(MockResponse::class, $response);
+        service('response')->setStatusCode(200);
+
+        Services::autoloader()->addNamespace(
+            'AfterAutoloadModule',
+            SUPPORTPATH . '_AfterAutoloadModule/'
+        );
+        Services::resetServicesCache();
+
+        $response = service('response');
+        $this->assertInstanceOf(MockResponse::class, $response);
+        $this->assertSame(200, $response->getStatusCode());
+
+        $test = service('test');
+        $this->assertInstanceOf(Test::class, $test);
+    }
+
     public function testFilters(): void
     {
         $result = Services::filters();

user_guide_src/source/changelogs/v4.6.0.rst

@@ -157,6 +157,8 @@ Others
 
 - **Filters:** Now you can execute a filter more than once with the different
   arguments in before or after.
+- **Services:** Added ``BaseService::resetServicesCache()`` method to reset
+  the services cache. See :ref:`resetting-services-cache`.
 
 ***************
 Message Changes

user_guide_src/source/concepts/services.rst

@@ -173,3 +173,20 @@ would simply use the framework's ``Config\Services`` class to grab your service:
 .. literalinclude:: services/012.php
 
 .. note:: If multiple Services files have the same method name, the first one found will be the instance returned.
+
+.. _resetting-services-cache:
+
+Resetting Services Cache
+========================
+
+.. versionadded:: 4.6.0
+
+When the Services class is first called fairly early in the framework initialization
+process, the Services classes discovered by auto-discovery are cached in a property,
+and it will not be updated.
+
+If modules are dynamically loaded later, and there are Services in the modules,
+the cache must be updated.
+
+This can be done by running ``Config\Services::resetServicesCache()``. This will
+clear the cache, and force the service discovery again when needed.