Return null for missing env vars

CHANGELOG-WIP.md

@@ -405,6 +405,7 @@
 - `craft\fields\Matrix::$propagationMethod` now has a type of `craft\enums\PropagationMethod`.
 - `craft\fields\fieldlayoutelements\BaseUiElement::selectorIcon()` can now return a system icon name. ([#14169](https://github.com/craftcms/cms/pull/14169))
 - `craft\gql\mutations\Entry::createSaveMutations()` now accepts a `$section` argument.
+- `craft\helpers\App::parseEnv()` now returns `null` when a missing environment variable name is passed to it. ([#14253](https://github.com/craftcms/cms/pull/14253))
 - `craft\helpers\Cp::fieldHtml()` now supports a `labelExtra` config value.
 - `craft\helpers\Db::parseParam()`, `parseDateParam()`, `parseMoneyParam()`, and `parseNumericParam()` now return `null` instead of an empty string if no condition should be applied.
 - `craft\helpers\Html::id()` and `Craft.formatInputId()` now retain colons and periods, and ensure the string begins with a letter.

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Release Notes for Craft CMS 5
 
+## Unreleased
+
+- `craft\helpers\App::parseEnv()` now returns `null` when a missing environment variable name is passed to it. ([#14253](https://github.com/craftcms/cms/pull/14253)) 
+
 ## 5.0.0-alpha.10 - 2024-01-30
 
 - Sites’ Language settings can now be set to environment variables. ([#14235](https://github.com/craftcms/cms/pull/14235), [#14135](https://github.com/craftcms/cms/discussions/14135))

src/helpers/App.php

@@ -177,6 +177,9 @@ public static function envConfig(string $class, ?string $envPrefix = null): arra
      * If the string references an environment variable with a value of `true`
      * or `false`, a boolean value will be returned.
      *
+     * If the string references an environment variable that’s not defined,
+     * `null` will be returned.
+     *
      * ---
      *
      * ```php
@@ -199,8 +202,8 @@ public static function parseEnv(?string $value): bool|string|null
             $env = static::env($matches[1]);
 
             if ($env === null) {
-                // starts with $ but not an environment variable/constant, so just give up, it's hopeless!
-                return $value;
+                // No env var or constant is defined here by that name
+                return null;
             }
 
             $value = $env;
@@ -241,7 +244,11 @@ public static function parseBooleanEnv(mixed $value): ?bool
             return null;
         }
 
-        return filter_var(static::parseEnv($value), FILTER_VALIDATE_BOOL, FILTER_NULL_ON_FAILURE);
+        $value = static::parseEnv($value);
+        if ($value === null) {
+            return null;
+        }
+        return filter_var($value, FILTER_VALIDATE_BOOL, FILTER_NULL_ON_FAILURE);
     }
 
     /**

tests/unit/helpers/AppHelperTest.php

@@ -94,7 +94,7 @@ public function testParseEnv(): void
         self::assertNull(App::parseEnv(null));
         self::assertSame(CRAFT_TESTS_PATH, App::parseEnv('$CRAFT_TESTS_PATH'));
         self::assertSame('CRAFT_TESTS_PATH', App::parseEnv('CRAFT_TESTS_PATH'));
-        self::assertSame('$TEST_MISSING', App::parseEnv('$TEST_MISSING'));
+        self::assertSame(null, App::parseEnv('$TEST_MISSING'));
         self::assertSame(Craft::getAlias('@vendor/foo'), App::parseEnv('@vendor/foo'));
     }
 
@@ -445,6 +445,7 @@ public static function parseBooleanEnvDataProvider(): array
             [true, 1],
             [false, 0],
             [null, 2],
+            [null, '$TEST_MISSING'],
         ];
     }