Fix #417: Add .env for development without Docker

.env.example

@@ -0,0 +1,5 @@
+# Local environment configuration.
+# Copy this file to .env and adjust as needed.
+# In production, set environment variables via server or container configuration instead.
+APP_ENV=dev
+APP_DEBUG=true

.gitignore

@@ -24,3 +24,6 @@ Thumbs.db
 
 # Codeception C3
 c3.php
+
+# Local environment configuration
+.env

CHANGELOG.md

@@ -9,6 +9,7 @@
 - Chg #449: Remove `yiisoft/data-response` dependency (@vjik)
 - Chg #443: Do not write logs to file since that's not needed for both Docker and `./yii serve` (@samdark)
 - Enh #456: Add "service update paused" case for swarm deployment log parsing (@samdark)
+- Enh #417: Add `.env` for development without Docker (@samdark)
 
 ## 1.2.0 February 20, 2026
 

README.md

@@ -47,15 +47,25 @@ cd myproject
 > [!NOTE]
 > Ensure that Composer is executed with the same PHP version that will be used to run the application.
 
+Copy the example environment file and adjust as needed:
+
+```shell
+cp .env.example .env
+```
+
 To run the app:
 
 ```shell
-APP_ENV=dev ./yii serve
+./yii serve
 ```
 
 Now you should be able to access the application through the URL printed to console.
 Usually it is `http://localhost:8080`.
 
+> [!TIP]
+> The `.env` file is for local development only and is excluded from version control.
+> In production, configure environment variables via your server or container instead.
+
 ### Installation with Docker
 
 > [!WARNING]
@@ -110,6 +120,7 @@ src/                    Application source code.
     Web/                Web-specific code (actions, handlers, layout).
         Shared/         Shared web components.
             Layout/     Layout components and templates.
+    bootstrap.php       Application bootstrap (autoloading, environment setup).
     Environment.php     Environment configuration class.
 tests/                  A set of Codeception tests for the application.
     Console/            Console command tests.

composer.json

@@ -66,6 +66,7 @@
         "yiisoft/yii-view-renderer": "^7.4.1"
     },
     "require-dev": {
+        "vlucas/phpdotenv": "^5.6",
         "codeception/c3": "^2.9",
         "codeception/codeception": "^5.3.5",
         "codeception/module-asserts": "^3.3.0",

public/index.php

@@ -12,7 +12,7 @@
 
 $root = dirname(__DIR__);
 
-require_once $root . '/src/autoload.php';
+require_once $root . '/src/bootstrap.php';
 
 if (Environment::appC3()) {
     $c3 = $root . '/c3.php';

src/Environment.php

@@ -78,19 +78,18 @@ public static function appDebug(): bool
 
     private static function setEnvironment(): void
     {
-        $environment = self::getRawValue('APP_ENV');
+        $environment = self::getRawValue('APP_ENV') ?: self::PROD;
 
         if (!in_array($environment, self::ENVIRONMENTS, true)) {
-            if ($environment === null) {
-                $message = 'APP_ENV environment variable is empty.';
-            } else {
-                $message = sprintf('APP_ENV="%s" environment is invalid.', $environment);
-            }
-
-            $message .= sprintf(' Valid values are "%s".', implode('", "', self::ENVIRONMENTS));
-
-            throw new RuntimeException($message);
+            throw new RuntimeException(
+                sprintf(
+                    'APP_ENV="%s" is invalid. Valid values are "%s".',
+                    $environment,
+                    implode('", "', self::ENVIRONMENTS),
+                ),
+            );
         }
+
         self::$values['APP_ENV'] = $environment;
     }
 

src/bootstrap.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Environment;
+
+require_once dirname(__DIR__) . '/vendor/autoload.php';
+
+// Load .env for non-Docker/non-container environments.
+// Existing process environment variables take precedence (Docker, CI, server config).
+// phpdotenv is a dev dependency — not available in production (composer install --no-dev).
+if (class_exists(\Dotenv\Dotenv::class)) {
+    \Dotenv\Dotenv::createImmutable(dirname(__DIR__))->safeLoad();
+}
+
+Environment::prepare();

yii

@@ -6,7 +6,7 @@ declare(strict_types=1);
 use App\Environment;
 use Yiisoft\Yii\Runner\Console\ConsoleApplicationRunner;
 
-require_once __DIR__ . '/src/autoload.php';
+require_once __DIR__ . '/src/bootstrap.php';
 
 // Run console application runner
 $runner = new ConsoleApplicationRunner(