feat: add the EnvironmentDetector utility class and envdetector service

system/CLI/CLI.php

@@ -656,7 +656,7 @@ public static function strlen(?string $string): int
      */
     public static function streamSupports(string $function, $resource): bool
     {
-        if (ENVIRONMENT === 'testing') {
+        if (service('envdetector')->isTesting()) {
             // In the current setup of the tests we cannot fully check
             // if the stream supports the function since we are using
             // filtered streams.

system/CLI/InputOutput.php

@@ -42,7 +42,7 @@ public function __construct()
     public function input(?string $prefix = null): string
     {
         // readline() can't be tested.
-        if ($this->readlineSupport && ENVIRONMENT !== 'testing') {
+        if ($this->readlineSupport && ! service('envdetector')->isTesting()) {
             return readline($prefix); // @codeCoverageIgnore
         }
 

system/Commands/Database/CreateDatabase.php

@@ -87,7 +87,7 @@ public function run(array $params)
             $config = config(Database::class);
 
             // Set to an empty database to prevent connection errors.
-            $group = ENVIRONMENT === 'testing' ? 'tests' : $config->defaultGroup;
+            $group = service('envdetector')->isTesting() ? 'tests' : $config->defaultGroup;
 
             $config->{$group}['database'] = '';
 

system/Commands/Database/MigrateRefresh.php

@@ -74,7 +74,7 @@ public function run(array $params)
     {
         $params['b'] = 0;
 
-        if (ENVIRONMENT === 'production') {
+        if (service('envdetector')->isProduction()) {
             // @codeCoverageIgnoreStart
             $force = array_key_exists('f', $params) || CLI::getOption('f');
 

system/Commands/Database/MigrateRollback.php

@@ -72,7 +72,7 @@ class MigrateRollback extends BaseCommand
      */
     public function run(array $params)
     {
-        if (ENVIRONMENT === 'production') {
+        if (service('envdetector')->isProduction()) {
             // @codeCoverageIgnoreStart
             $force = array_key_exists('f', $params) || CLI::getOption('f');
 

system/Commands/Database/MigrateStatus.php

@@ -92,7 +92,7 @@ public function run(array $params)
         $status = [];
 
         foreach (array_keys($namespaces) as $namespace) {
-            if (ENVIRONMENT !== 'testing') {
+            if (! service('envdetector')->isTesting()) {
                 // Make Tests\\Support discoverable for testing
                 $this->ignoredNamespaces[] = 'Tests\Support'; // @codeCoverageIgnore
             }

system/Commands/Translation/LocalizationFinder.php

@@ -61,7 +61,7 @@ public function run(array $params)
         $currentDir         = APPPATH;
         $this->languagePath = $currentDir . 'Language';
 
-        if (ENVIRONMENT === 'testing') {
+        if (service('envdetector')->isTesting()) {
             $currentDir         = SUPPORTPATH . 'Services' . DIRECTORY_SEPARATOR;
             $this->languagePath = SUPPORTPATH . 'Language';
         }

system/Commands/Translation/LocalizationSync.php

@@ -85,7 +85,7 @@ public function run(array $params)
             return EXIT_USER_INPUT;
         }
 
-        if (ENVIRONMENT === 'testing') {
+        if (service('envdetector')->isTesting()) {
             $this->languagePath = SUPPORTPATH . 'Language';
         }
 

system/Config/BaseService.php

@@ -29,6 +29,7 @@
 use CodeIgniter\Debug\Toolbar;
 use CodeIgniter\Email\Email;
 use CodeIgniter\Encryption\EncrypterInterface;
+use CodeIgniter\EnvironmentDetector;
 use CodeIgniter\Exceptions\InvalidArgumentException;
 use CodeIgniter\Filters\Filters;
 use CodeIgniter\Format\Format;
@@ -111,6 +112,7 @@
  * @method static CURLRequest                curlrequest($options = [], ResponseInterface $response = null, App $config = null, $getShared = true)
  * @method static Email                      email($config = null, $getShared = true)
  * @method static EncrypterInterface         encrypter(Encryption $config = null, $getShared = false)
+ * @method static EnvironmentDetector        envdetector(?string $environment = null, bool $getShared = true)
  * @method static Exceptions                 exceptions(ConfigExceptions $config = null, $getShared = true)
  * @method static Filters                    filters(ConfigFilters $config = null, $getShared = true)
  * @method static Format                     format(ConfigFormat $config = null, $getShared = true)

system/Config/Services.php

@@ -28,6 +28,7 @@
 use CodeIgniter\Email\Email;
 use CodeIgniter\Encryption\EncrypterInterface;
 use CodeIgniter\Encryption\Encryption;
+use CodeIgniter\EnvironmentDetector;
 use CodeIgniter\Filters\Filters;
 use CodeIgniter\Format\Format;
 use CodeIgniter\Honeypot\Honeypot;
@@ -259,6 +260,23 @@ public static function encrypter(?EncryptionConfig $config = null, $getShared =
         return $encryption->initialize($config);
     }
 
+    /**
+     * Provides a simple way to determine the current environment
+     * of the application.
+     *
+     * 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 envdetector(?string $environment = null, bool $getShared = true): EnvironmentDetector
+    {
+        if ($getShared) {
+            return static::getSharedInstance('envdetector', $environment);
+        }
+
+        return new EnvironmentDetector($environment);
+    }
+
     /**
      * The Exceptions class holds the methods that handle:
      *

system/Database/Config.php

@@ -61,7 +61,7 @@ public static function connect($group = null, bool $getShared = true)
             $dbConfig = config(DbConfig::class);
 
             if ($group === null) {
-                $group = (ENVIRONMENT === 'testing') ? 'tests' : $dbConfig->defaultGroup;
+                $group = service('envdetector')->isTesting() ? 'tests' : $dbConfig->defaultGroup;
             }
 
             assert(is_string($group));

system/Database/MigrationRunner.php

@@ -448,7 +448,7 @@ public function findMigrations(): array
         $migrations = [];
 
         foreach ($namespaces as $namespace) {
-            if (ENVIRONMENT !== 'testing' && $namespace === 'Tests\Support') {
+            if (! service('envdetector')->isTesting() && $namespace === 'Tests\Support') {
                 continue;
             }
 
@@ -985,7 +985,7 @@ protected function migrate($direction, $migration): bool
         $instance = new $class(Database::forge($this->db));
         $group    = $instance->getDBGroup() ?? $this->group;
 
-        if (ENVIRONMENT !== 'testing' && $group === 'tests' && $this->groupFilter !== 'tests') {
+        if (! service('envdetector')->isTesting() && $group === 'tests' && $this->groupFilter !== 'tests') {
             // @codeCoverageIgnoreStart
             $this->groupSkip = true;
 

system/Debug/ExceptionHandler.php

@@ -94,7 +94,7 @@ public function handle(
 
                 $this->respond($data, $statusCode)->send();
 
-                if (ENVIRONMENT !== 'testing') {
+                if (! service('envdetector')->isTesting()) {
                     exit($exitCode); // @codeCoverageIgnore
                 }
 
@@ -123,7 +123,7 @@ public function handle(
         // Displays the HTML or CLI error code.
         $this->render($exception, $statusCode, $viewFile);
 
-        if (ENVIRONMENT !== 'testing') {
+        if (! service('envdetector')->isTesting()) {
             exit($exitCode); // @codeCoverageIgnore
         }
     }

system/Debug/Toolbar.php

@@ -457,7 +457,7 @@ public function prepare(?RequestInterface $request = null, ?ResponseInterface $r
      */
     public function respond(): void
     {
-        if (ENVIRONMENT === 'testing') {
+        if (service('envdetector')->isTesting()) {
             return;
         }
 

system/Debug/Toolbar/Collectors/Config.php

@@ -32,7 +32,7 @@ public static function display(): array
             'ciVersion'   => CodeIgniter::CI_VERSION,
             'phpVersion'  => PHP_VERSION,
             'phpSAPI'     => PHP_SAPI,
-            'environment' => ENVIRONMENT,
+            'environment' => service('envdetector')->get(),
             'baseURL'     => $config->baseURL,
             'timezone'    => app_timezone(),
             'locale'      => service('request')->getLocale(),

system/EnvironmentDetector.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) 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;
+
+use CodeIgniter\Exceptions\InvalidArgumentException;
+
+/**
+ * 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 `envdetector` 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()}.
+ *
+ * @see \CodeIgniter\EnvironmentDetectorTest
+ */
+final readonly class EnvironmentDetector
+{
+    private string $environment;
+
+    /**
+     * @param non-empty-string|null $environment The environment to use, or null to
+     *                                           fall back to the `ENVIRONMENT` constant.
+     */
+    public function __construct(?string $environment = null)
+    {
+        $environment = $environment !== null ? trim($environment) : ENVIRONMENT;
+
+        if ($environment === '') {
+            throw new InvalidArgumentException('Environment cannot be an empty string.');
+        }
+
+        $this->environment = $environment;
+    }
+
+    public function get(): string
+    {
+        return $this->environment;
+    }
+
+    /**
+     * Checks if the current environment matches any of the given environments.
+     *
+     * @param string ...$environments One or more environment names to check against.
+     */
+    public function is(string ...$environments): bool
+    {
+        return in_array($this->environment, $environments, true);
+    }
+
+    public function isProduction(): bool
+    {
+        return $this->is('production');
+    }
+
+    public function isDevelopment(): bool
+    {
+        return $this->is('development');
+    }
+
+    public function isTesting(): bool
+    {
+        return $this->is('testing');
+    }
+}

system/Format/JSONFormatter.php

@@ -37,7 +37,7 @@ public function format($data)
         $options = $config->formatterOptions['application/json'] ?? JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES;
         $options |= JSON_PARTIAL_OUTPUT_ON_ERROR;
 
-        if (ENVIRONMENT !== 'production') {
+        if (! service('envdetector')->isProduction()) {
             $options |= JSON_PRETTY_PRINT;
         }
 

system/HTTP/DownloadResponse.php

@@ -247,7 +247,7 @@ public function noCache(): self
     public function send()
     {
         // Turn off output buffering completely, even if php.ini output_buffering is not off
-        if (ENVIRONMENT !== 'testing') {
+        if (! service('envdetector')->isTesting()) {
             while (ob_get_level() > 0) {
                 ob_end_clean();
             }

system/HTTP/SSEResponse.php

@@ -137,7 +137,7 @@ private function write(string $output): bool
     {
         echo $output;
 
-        if (ENVIRONMENT !== 'testing') {
+        if (! service('envdetector')->isTesting()) {
             if (ob_get_level() > 0) {
                 ob_flush();
             }
@@ -156,7 +156,7 @@ private function write(string $output): bool
     public function send()
     {
         // Turn off output buffering completely, even if php.ini output_buffering is not off
-        if (ENVIRONMENT !== 'testing') {
+        if (! service('envdetector')->isTesting()) {
             set_time_limit(0);
             ini_set('zlib.output_compression', 'Off');
 

system/Helpers/form_helper.php

@@ -703,7 +703,7 @@ function validation_errors()
 
         // Check the session to see if any were
         // passed along from a redirect withErrors() request.
-        if ($errors !== null && (ENVIRONMENT === 'testing' || ! is_cli())) {
+        if ($errors !== null && (service('envdetector')->isTesting() || ! is_cli())) {
             return $errors;
         }
 

system/Log/Logger.php

@@ -401,7 +401,7 @@ protected function interpolate($message, array $context = [])
 
         $replace['{post_vars}'] = '$_POST: ' . print_r(service('superglobals')->getPostArray(), true);
         $replace['{get_vars}']  = '$_GET: ' . print_r(service('superglobals')->getGetArray(), true);
-        $replace['{env}']       = ENVIRONMENT;
+        $replace['{env}']       = service('envdetector')->get();
 
         // Allow us to log the file/line that we are logging from
         if (str_contains($message, '{file}') || str_contains($message, '{line}')) {

system/Router/Attributes/Restrict.php

@@ -69,7 +69,7 @@ protected function checkEnvironment(): void
             return;
         }
 
-        $currentEnv = ENVIRONMENT;
+        $currentEnv = service('envdetector')->get();
         $allowed    = [];
         $denied     = [];
 

system/Router/RouteCollection.php

@@ -1163,7 +1163,7 @@ public function view(string $from, string $view, ?array $options = null): RouteC
      */
     public function environment(string $env, Closure $callback): RouteCollectionInterface
     {
-        if ($env === ENVIRONMENT) {
+        if (service('envdetector')->is($env)) {
             $callback($this);
         }
 

system/Session/Session.php

@@ -86,7 +86,7 @@ public function __construct(SessionHandlerInterface $driver, SessionConfig $conf
      */
     public function start()
     {
-        if (is_cli() && ENVIRONMENT !== 'testing') {
+        if (is_cli() && ! service('envdetector')->isTesting()) {
             // @codeCoverageIgnoreStart
             $this->logger->debug('Session: Initialization under CLI aborted.');
 
@@ -273,7 +273,7 @@ private function removeOldSessionCookie(): void
 
     public function destroy()
     {
-        if (ENVIRONMENT === 'testing') {
+        if (service('envdetector')->isTesting()) {
             return;
         }
 
@@ -287,7 +287,7 @@ public function destroy()
      */
     public function close()
     {
-        if (ENVIRONMENT === 'testing') {
+        if (service('envdetector')->isTesting()) {
             return;
         }
 
@@ -616,7 +616,7 @@ protected function setSaveHandler()
      */
     protected function startSession()
     {
-        if (ENVIRONMENT === 'testing') {
+        if (service('envdetector')->isTesting()) {
             $_SESSION = [];
 
             return;

system/Validation/StrictRules/FileRules.php

@@ -62,17 +62,14 @@ public function uploaded(?string $blank, string $name): bool
                 return false;
             }
 
-            if (ENVIRONMENT === 'testing') {
-                if ($file->getError() !== 0) {
-                    return false;
-                }
-            } else {
-                // Note: cannot unit test this; no way to over-ride ENVIRONMENT?
-                // @codeCoverageIgnoreStart
-                if (! $file->isValid()) {
-                    return false;
-                }
-                // @codeCoverageIgnoreEnd
+            // In the testing env is_uploaded_file() always returns false
+            // (fixtures aren't real HTTP uploads), so check the error code directly.
+            $isValid = service('envdetector')->isTesting()
+                ? $file->getError() === UPLOAD_ERR_OK
+                : $file->isValid();
+
+            if (! $isValid) {
+                return false;
             }
         }