address review suggestions

Author: paulbalandan

system/Config/Services.php

@@ -264,9 +264,11 @@ public static function encrypter(?EncryptionConfig $config = null, $getShared =
      * Provides a simple way to determine the current environment
      * of the application.
      *
-     * @return EnvironmentDetector
+     * Primarily intended for testing environment-specific branches by
+     * mocking this service. Mocking it does not modify the `ENVIRONMENT`
+     * constant. It only affects code paths that resolve and use this service.
      */
-    public static function environmentdetector(?string $environment = null, bool $getShared = true)
+    public static function environmentdetector(?string $environment = null, bool $getShared = true): EnvironmentDetector
     {
         if ($getShared) {
             return static::getSharedInstance('environmentdetector', $environment);

system/EnvironmentDetector.php

@@ -18,6 +18,13 @@
 /**
  * Provides a simple way to determine the current environment of the application.
  *
+ * Primarily intended as a mockable seam for testing environment-specific code
+ * paths that resolve this class via the `environmentdetector` service.
+ *
+ * It does not redefine the `ENVIRONMENT` constant. It affects only code paths
+ * that resolve and use this class, while code that still reads `ENVIRONMENT`
+ * directly keeps its current behavior.
+ *
  * For custom environment names beyond the built-in production/development/testing,
  * use {@see self::is()}.
  *

user_guide_src/source/general/environments.rst

@@ -161,6 +161,13 @@ constant.
 
 .. literalinclude:: environments/001.php
 
+.. note::
+
+    The ``environmentdetector`` service is primarily intended for testing
+    environment-specific code paths. Mocking it only affects code that resolves
+    and uses the service itself. It does not modify the ``ENVIRONMENT`` constant.
+    Code that still reads ``ENVIRONMENT`` directly keeps its current behavior.
+
 Passing a value to the constructor overrides the detected environment; passing
 ``null`` (the default) falls back to the ``ENVIRONMENT`` constant. An empty or
 whitespace-only string throws ``CodeIgniter\Exceptions\InvalidArgumentException``.