feat(core)!: make Environment its own source of truth (#1838)

Author: innocenzi

docs/1-essentials/06-configuration.md

@@ -28,30 +28,30 @@ return new PostgresConfig(
 
 The configuration object above instructs Tempest to use PostgreSQL as its database, replacing the framework's default database, SQLite.
 
-## Accessing configuration objects
+### Accessing configuration objects
 
 To access a configuration object, you may inject it from the container like any other dependency.
 
 ```php
-use Tempest\Core\AppConfig;
+use Tempest\Core\Environment;
 
-final readonly class HomeController
+final readonly class AboutController
 {
     public function __construct(
-        private AppConfig $config,
+        private Environment $environment,
     ) {}
 
     #[Get('/')]
     public function __invoke(): View
     {
-        return view('home.view.php', environment: $this->config->environment);
+        return view('about.view.php', environment: $this->environment);
     }
 }
 ```
 
-## Updating configuration objects
+### Updating configuration objects
 
-To update a property in a configuration object, you may simply assign a new value. Due to the object being a singleton, the modification will be persisted throught the rest of the application's lifecycle.
+To update a property in a configuration object, you may simply assign a new value. Due to the object being a singleton, the modification will be persisted through the rest of the application's lifecycle.
 
 ```php
 use Tempest\Support\Random;
@@ -81,7 +81,7 @@ final class SlackConfig
         public string $token,
         public string $baseUrl,
         public string $applicationId,
-        public string $userAgent,
+        public ?string $userAgent = null,
     ) {}
 }
 ```
@@ -120,7 +120,7 @@ final class SlackConnector extends HttpConnector
 
 ## Per-environment configuration
 
-Whenever possible, you should have a single configuration file per feature. You may use the `Tempest\env()` function inside that file to reference credentials and environment-specific values.
+Whenever possible, you should have a single configuration file per feature. You may use the {b`Tempest\env()`} function inside that file to reference credentials and environment-specific values.
 
 However, it's sometimes needed to have completely different configurations in development and in production. For instance, you may use S3 for your [storage](../2-features/05-file-storage.md) in production, but use the local filesystem during development.
 
@@ -135,6 +135,13 @@ return new S3StorageConfig(
 );
 ```
 
+The following suffixes are supported:
+
+- `.prd.config.php`, `.prod.config.php`, and `.production.config.php` for the production environment.
+- `.stg.config.php` and `.staging.config.php` for the staging environment.
+- `.dev.config.php` and `.local.config.php` for the development environment.
+- `.test.config.php` and `.testing.config.php` for the testing environment.
+
 ## Disabling the configuration cache
 
 During development, Tempest will discover configuration files every time the framework is booted. In a production environment, configuration files are automatically cached.

docs/1-essentials/07-testing.md

@@ -125,6 +125,18 @@ $this->console
 
 And many, many more.
 
+## Spoofing the environment
+
+By default, Tempest provides a `phpunit.xml` that sets the `ENVIRONMENT` variable to `testing`. This is needed so that Tempest can adapt its boot process and load the proper configuration files for the testing environment.
+
+During tests, you may want to test different paths of your application depending on the environment. For instance, you may want to test that certain features are only available in production. To do this, you may override the {b`Tempest\Core\Environment`} singleton:
+
+```php
+use Tempest\Core\Environment;
+
+$this->container->singleton(Environment::class, Environment::PRODUCTION);
+```
+
 ## Changing the location of tests
 
 The `phpunit.xml` file contains a `{html}<testsuite>` element that configures the directory in which PHPUnit looks for test files. This may be changed to follow any rule of your convenience.

packages/cache/src/Commands/CacheStatusCommand.php

@@ -12,25 +12,25 @@
 use Tempest\Console\HasConsole;
 use Tempest\Container\Container;
 use Tempest\Container\GenericContainer;
-use Tempest\Core\AppConfig;
 use Tempest\Core\ConfigCache;
 use Tempest\Core\DiscoveryCache;
+use Tempest\Core\Environment;
 use Tempest\Icon\IconCache;
 use Tempest\Support\Str;
 use Tempest\View\ViewCache;
 use UnitEnum;
 
 use function Tempest\Support\arr;
 
-if (class_exists(\Tempest\Console\ConsoleCommand::class)) {
+if (class_exists(ConsoleCommand::class)) {
     final readonly class CacheStatusCommand
     {
         use HasConsole;
 
         public function __construct(
             private Console $console,
             private Container $container,
-            private AppConfig $appConfig,
+            private Environment $environment,
             private DiscoveryCache $discoveryCache,
         ) {}
 
@@ -73,7 +73,7 @@ public function __invoke(bool $internal = true): void
                     },
                 );
 
-                if ($this->appConfig->environment->isProduction() && ! $this->discoveryCache->enabled) {
+                if ($this->environment->requiresCaution() && ! $this->discoveryCache->enabled) {
                     $this->console->writeln();
                     $this->console->error('Discovery cache is disabled in production. This is not recommended.');
                 }

packages/console/src/Middleware/CautionMiddleware.php

@@ -9,22 +9,20 @@
 use Tempest\Console\ConsoleMiddlewareCallable;
 use Tempest\Console\ExitCode;
 use Tempest\Console\Initializers\Invocation;
-use Tempest\Core\AppConfig;
+use Tempest\Core\Environment;
 use Tempest\Discovery\SkipDiscovery;
 
 #[SkipDiscovery]
 final readonly class CautionMiddleware implements ConsoleMiddleware
 {
     public function __construct(
         private Console $console,
-        private AppConfig $appConfig,
+        private Environment $environment,
     ) {}
 
     public function __invoke(Invocation $invocation, ConsoleMiddlewareCallable $next): ExitCode|int
     {
-        $environment = $this->appConfig->environment;
-
-        if ($environment->isProduction() || $environment->isStaging()) {
+        if ($this->environment->requiresCaution()) {
             if ($this->console->isForced) {
                 return $next($invocation);
             }

packages/core/src/AppConfig.php

@@ -8,15 +8,11 @@
 
 final class AppConfig
 {
-    public Environment $environment;
-
     public string $baseUri;
 
     public function __construct(
         public ?string $name = null,
 
-        ?Environment $environment = null,
-
         ?string $baseUri = null,
 
         /** @var class-string<\Tempest\Core\ExceptionProcessor>[] */
@@ -27,7 +23,6 @@ public function __construct(
          */
         public array $insightsProviders = [],
     ) {
-        $this->environment = $environment ?? Environment::fromEnv();
         $this->baseUri = $baseUri ?? env('BASE_URI') ?? '';
     }
 }

packages/core/src/Commands/DiscoveryGenerateCommand.php

@@ -9,10 +9,10 @@
 use Tempest\Console\HasConsole;
 use Tempest\Container\Container;
 use Tempest\Container\GenericContainer;
-use Tempest\Core\AppConfig;
 use Tempest\Core\DiscoveryCache;
 use Tempest\Core\DiscoveryCacheStrategy;
 use Tempest\Core\DiscoveryConfig;
+use Tempest\Core\Environment;
 use Tempest\Core\FrameworkKernel;
 use Tempest\Core\Kernel;
 use Tempest\Core\Kernel\LoadDiscoveryClasses;
@@ -27,7 +27,7 @@
         public function __construct(
             private Kernel $kernel,
             private DiscoveryCache $discoveryCache,
-            private AppConfig $appConfig,
+            private Environment $environment,
         ) {}
 
         #[ConsoleCommand(
@@ -37,7 +37,7 @@ public function __construct(
         )]
         public function __invoke(): void
         {
-            $strategy = DiscoveryCacheStrategy::make(env('DISCOVERY_CACHE', default: $this->appConfig->environment->isProduction()));
+            $strategy = DiscoveryCacheStrategy::make(env('DISCOVERY_CACHE', default: $this->environment->requiresCaution()));
 
             if ($strategy === DiscoveryCacheStrategy::NONE) {
                 $this->info('Discovery cache disabled, nothing to generate.');

packages/core/src/ConfigCacheInitializer.php

@@ -14,18 +14,16 @@ final class ConfigCacheInitializer implements Initializer
     public function initialize(Container $container): ConfigCache
     {
         return new ConfigCache(
-            enabled: $this->shouldCacheBeEnabled(
-                $container->get(AppConfig::class)->environment->isProduction(),
-            ),
+            enabled: $this->shouldCacheBeEnabled(),
         );
     }
 
-    private function shouldCacheBeEnabled(bool $isProduction): bool
+    private function shouldCacheBeEnabled(): bool
     {
         if (env('INTERNAL_CACHES') === false) {
             return false;
         }
 
-        return (bool) env('CONFIG_CACHE', default: $isProduction);
+        return (bool) env('CONFIG_CACHE', default: Environment::guessFromEnvironment()->requiresCaution());
     }
 }

packages/core/src/DiscoveryCacheInitializer.php

@@ -14,19 +14,17 @@ final class DiscoveryCacheInitializer implements Initializer
     public function initialize(Container $container): DiscoveryCache
     {
         return new DiscoveryCache(
-            strategy: $this->resolveDiscoveryCacheStrategy(
-                $container->get(AppConfig::class)->environment->isProduction(),
-            ),
+            strategy: $this->resolveDiscoveryCacheStrategy(),
         );
     }
 
-    private function resolveDiscoveryCacheStrategy(bool $isProduction): DiscoveryCacheStrategy
+    private function resolveDiscoveryCacheStrategy(): DiscoveryCacheStrategy
     {
         if ($this->isDiscoveryGenerateCommand() || $this->isDiscoveryClearCommand()) {
             return DiscoveryCacheStrategy::NONE;
         }
 
-        $current = DiscoveryCacheStrategy::make(env('DISCOVERY_CACHE', default: $isProduction));
+        $current = DiscoveryCacheStrategy::make(env('DISCOVERY_CACHE', default: Environment::guessFromEnvironment()->requiresCaution()));
 
         if ($current === DiscoveryCacheStrategy::NONE) {
             return $current;

packages/core/src/Environment.php

@@ -6,14 +6,24 @@
 
 use function Tempest\env;
 
+/**
+ * Represents the environment in which the application is running.
+ */
 enum Environment: string
 {
     case LOCAL = 'local';
     case STAGING = 'staging';
     case PRODUCTION = 'production';
-    case CI = 'ci';
+    case CONTINUOUS_INTEGRATION = 'ci';
     case TESTING = 'testing';
-    case OTHER = 'other';
+
+    /**
+     * Determines if this environment requires caution for destructive operations.
+     */
+    public function requiresCaution(): bool
+    {
+        return in_array($this, [self::PRODUCTION, self::STAGING], strict: true);
+    }
 
     public function isProduction(): bool
     {
@@ -30,24 +40,27 @@ public function isLocal(): bool
         return $this === self::LOCAL;
     }
 
-    public function isCI(): bool
+    public function isContinuousIntegration(): bool
     {
-        return $this === self::CI;
+        return $this === self::CONTINUOUS_INTEGRATION;
     }
 
     public function isTesting(): bool
     {
         return $this === self::TESTING;
     }
 
-    public function isOther(): bool
+    /**
+     * Guesses the environment from the `ENVIRONMENT` environment variable.
+     */
+    public static function guessFromEnvironment(): self
     {
-        return $this === self::OTHER;
-    }
+        $value = env('ENVIRONMENT', default: 'local');
 
-    public static function fromEnv(): self
-    {
-        $value = env('ENVIRONMENT', 'local');
+        // Can be removed after https://github.com/tempestphp/tempest-framework/pull/1836
+        if (is_null($value)) {
+            $value = 'local';
+        }
 
         return self::tryFrom($value) ?? throw new EnvironmentValueWasInvalid($value);
     }

packages/core/src/EnvironmentInitalizer.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Tempest\Core;
+
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Container\Singleton;
+
+final class EnvironmentInitalizer implements Initializer
+{
+    #[Singleton]
+    public function initialize(Container $container): Environment
+    {
+        return Environment::guessFromEnvironment();
+    }
+}