add EnvironmentDetector utility class

Author: paulbalandan

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,21 @@ public static function encrypter(?EncryptionConfig $config = null, $getShared =
         return $encryption->initialize($config);
     }
 
+    /**
+     * Provides a simple way to determine the current environment
+     * of the application.
+     *
+     * @return EnvironmentDetector
+     */
+    public static function environmentdetector(?string $environment = null, bool $getShared = true)
+    {
+        if ($getShared) {
+            return static::getSharedInstance('environmentdetector', $environment);
+        }
+
+        return new EnvironmentDetector($environment);
+    }
+
     /**
      * The Exceptions class holds the methods that handle:
      *

system/EnvironmentDetector.php

@@ -0,0 +1,72 @@
+<?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 CodeIgniter;
+
+use CodeIgniter\Exceptions\InvalidArgumentException;
+
+/**
+ * Provides a simple way to determine the current environment of the application.
+ *
+ * For custom environment names beyond the built-in production/development/testing,
+ * use {@see self::is()}.
+ *
+ * @see \CodeIgniter\EnvironmentDetectorTest
+ */
+final class EnvironmentDetector
+{
+    private readonly 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)
+    {
+        if ($environment !== null && trim($environment) === '') {
+            throw new InvalidArgumentException('Environment cannot be an empty string.');
+        }
+
+        $this->environment = $environment !== null ? trim($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');
+    }
+}

tests/system/EnvironmentDetectorTest.php

@@ -0,0 +1,130 @@
+<?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 CodeIgniter;
+
+use CodeIgniter\Exceptions\InvalidArgumentException;
+use CodeIgniter\Test\CIUnitTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Group;
+
+/**
+ * @internal
+ */
+#[Group('Others')]
+final class EnvironmentDetectorTest extends CIUnitTestCase
+{
+    public function testDefaultsToEnvironmentConstant(): void
+    {
+        $detector = new EnvironmentDetector();
+
+        $this->assertSame(ENVIRONMENT, $detector->get());
+    }
+
+    public function testExplicitEnvironmentOverridesConstant(): void
+    {
+        $detector = new EnvironmentDetector('production');
+
+        $this->assertSame('production', $detector->get());
+    }
+
+    public function testTrimsSurroundingWhitespace(): void
+    {
+        $detector = new EnvironmentDetector("  production\n");
+
+        $this->assertSame('production', $detector->get());
+    }
+
+    public function testRejectsEmptyString(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Environment cannot be an empty string.');
+
+        new EnvironmentDetector(''); // @phpstan-ignore argument.type
+    }
+
+    public function testRejectsWhitespaceOnlyString(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Environment cannot be an empty string.');
+
+        new EnvironmentDetector("  \t\n");
+    }
+
+    public function testIsMatchesSingleEnvironment(): void
+    {
+        $detector = new EnvironmentDetector('staging');
+
+        $this->assertTrue($detector->is('staging'));
+        $this->assertFalse($detector->is('production'));
+    }
+
+    public function testIsMatchesAnyOfSeveralEnvironments(): void
+    {
+        $detector = new EnvironmentDetector('staging');
+
+        $this->assertTrue($detector->is('production', 'staging', 'development'));
+        $this->assertFalse($detector->is('production', 'development', 'testing'));
+    }
+
+    public function testIsReturnsFalseWhenNoEnvironmentsGiven(): void
+    {
+        $detector = new EnvironmentDetector('production');
+
+        $this->assertFalse($detector->is());
+    }
+
+    public function testIsIsCaseSensitive(): void
+    {
+        $detector = new EnvironmentDetector('production');
+
+        $this->assertFalse($detector->is('Production'));
+        $this->assertFalse($detector->is('PRODUCTION'));
+    }
+
+    /**
+     * @param non-empty-string $environment
+     */
+    #[DataProvider('provideBuiltInEnvironmentHelpers')]
+    public function testBuiltInEnvironmentHelpers(string $environment, bool $isProduction, bool $isDevelopment, bool $isTesting): void
+    {
+        $detector = new EnvironmentDetector($environment);
+
+        $this->assertSame($isProduction, $detector->isProduction());
+        $this->assertSame($isDevelopment, $detector->isDevelopment());
+        $this->assertSame($isTesting, $detector->isTesting());
+    }
+
+    /**
+     * @return iterable<string, array{string, bool, bool, bool}>
+     */
+    public static function provideBuiltInEnvironmentHelpers(): iterable
+    {
+        yield 'production' => ['production', true, false, false];
+
+        yield 'development' => ['development', false, true, false];
+
+        yield 'testing' => ['testing', false, false, true];
+
+        yield 'custom' => ['staging', false, false, false];
+    }
+
+    public function testResolvesAsSharedService(): void
+    {
+        $first  = service('environmentdetector');
+        $second = service('environmentdetector');
+
+        $this->assertInstanceOf(EnvironmentDetector::class, $first);
+        $this->assertSame($first, $second);
+    }
+}