Add Env::getCast optional casting, docs, and tests

Author: KolesnikovKirill

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this package will be documented in this file.
 
+## [2.3.0] - 2026-01-03
+
+### Added
+
+-   `Env::getCast()` for optional casting of common string values.
+
+### Tests
+
+-   Added coverage for `Env::getCast()` casting behavior.
+
 ## [2.2.0] - 2025-12-28
 
 ### Added

README.md

@@ -48,6 +48,13 @@ Env::load(__DIR__ . '/.env');
 echo Env::get('APP_NAME'); // "MyApp"
 ```
 
+Optional casting:
+
+```php
+Env::getCast('FEATURE_ENABLED', false, true); // true
+Env::getCast('OPTIONAL_VALUE', 'default', true); // null
+```
+
 Common options:
 
 ```php
@@ -104,14 +111,14 @@ $loader->loadFiles([__DIR__ . '/.env', __DIR__ . '/.env.local']);
 
 Notes:
 
-- When encoding is null, no conversion is performed, even if mbstring is available.
-- UTF-8 BOM is stripped automatically.
+-   When encoding is null, no conversion is performed, even if mbstring is available.
+-   UTF-8 BOM is stripped automatically.
 
 ## Features
 
 -   Loading `.env` files into `$_ENV`, `$_SERVER`, and via `putenv()`.
 -   Does not override variables already present in `$_ENV`, `$_SERVER`, or `getenv()`.
--   Values are returned as strings; no automatic casting is applied.
+-   Values are returned as strings by default; `Env::getCast()` enables optional casting.
 -   Quoted strings with escaped quotes and `\n`, `\r`, `\t`, `\v`, `\f` in double quotes (single quotes are literal).
 -   Inline comments start with `#` in unquoted values (use quotes to keep a literal `#`).
 -   Unquoted values cannot contain whitespace.
@@ -128,31 +135,31 @@ Notes:
 
 ## Parse Formats
 
-| Method | Return format |
-| --- | --- |
-| `Env::parse()` | Raw entries: `[[name, value, vars], ...]` |
-| `Env::parseToArray()` | Associative map: `['NAME' => 'value', ...]` |
-| `EnvParser::parseStringRaw()` | Raw entries: `[[name, value, vars], ...]` |
+| Method                        | Return format                               |
+| ----------------------------- | ------------------------------------------- |
+| `Env::parse()`                | Raw entries: `[[name, value, vars], ...]`   |
+| `Env::parseToArray()`         | Associative map: `['NAME' => 'value', ...]` |
+| `EnvParser::parseStringRaw()` | Raw entries: `[[name, value, vars], ...]`   |
 
 Strict mode throws `InvalidFileException` on duplicate names for `parse()` and `parseToArray()`.
 
 ## Load Files Order
 
-- `loadFiles()` processes paths in the order provided.
-- Glob patterns are expanded using `glob()` with `GLOB_BRACE` by default.
-- Glob matches are sorted to keep load order stable.
-- Use the optional `globFlags` parameter to change `glob()` behavior.
-- If `strictResolve` is true, unresolved `${VAR}` or `$VAR` references in any loaded file will throw `InvalidFileException`.
-- If `shortCircuit` is true, the first successfully loaded file stops further processing.
-- If `shortCircuit` is false, missing files raise `InvalidPathException`.
+-   `loadFiles()` processes paths in the order provided.
+-   Glob patterns are expanded using `glob()` with `GLOB_BRACE` by default.
+-   Glob matches are sorted to keep load order stable.
+-   Use the optional `globFlags` parameter to change `glob()` behavior.
+-   If `strictResolve` is true, unresolved `${VAR}` or `$VAR` references in any loaded file will throw `InvalidFileException`.
+-   If `shortCircuit` is true, the first successfully loaded file stops further processing.
+-   If `shortCircuit` is false, missing files raise `InvalidPathException`.
 
 ## Exceptions
 
-| Scenario | Exception |
-| --- | --- |
-| Invalid syntax, invalid name, bad escapes | `Codemonster\Env\Exception\InvalidFileException` |
-| Invalid or unsupported encoding | `Codemonster\Env\Exception\InvalidEncodingException` |
-| Missing or unreadable file | `Codemonster\Env\Exception\InvalidPathException` |
+| Scenario                                  | Exception                                            |
+| ----------------------------------------- | ---------------------------------------------------- |
+| Invalid syntax, invalid name, bad escapes | `Codemonster\Env\Exception\InvalidFileException`     |
+| Invalid or unsupported encoding           | `Codemonster\Env\Exception\InvalidEncodingException` |
+| Missing or unreadable file                | `Codemonster\Env\Exception\InvalidPathException`     |
 
 ## Loader Interface
 

src/Env.php

@@ -116,6 +116,25 @@ public static function get(string $key, mixed $default = null): mixed
         return $value === false ? $default : $value;
     }
 
+    public static function getCast(string $key, mixed $default = null, bool $cast = false): mixed
+    {
+        if (!$cast) {
+            return self::get($key, $default);
+        }
+
+        if (array_key_exists($key, $_ENV)) {
+            return self::castValue($_ENV[$key]);
+        }
+
+        if (array_key_exists($key, $_SERVER)) {
+            return self::castValue($_SERVER[$key]);
+        }
+
+        $value = getenv($key);
+
+        return $value === false ? $default : self::castValue($value);
+    }
+
     public static function parse(
         string $content,
         ?string $encoding = null,
@@ -179,4 +198,38 @@ protected static function getDefaultLoaderInternal(): LoaderInterface
 
         return self::$defaultLoader;
     }
+
+    private static function castValue(mixed $value): mixed
+    {
+        if (!is_string($value)) {
+            return $value;
+        }
+
+        $trimmed = trim($value);
+        $lower = strtolower($trimmed);
+
+        return match ($lower) {
+            'true', '(true)' => true,
+            'false', '(false)' => false,
+            'empty', '(empty)' => '',
+            'null', '(null)' => null,
+            default => self::stripQuotes($trimmed) ?? $value,
+        };
+    }
+
+    private static function stripQuotes(string $value): ?string
+    {
+        if (strlen($value) < 2) {
+            return null;
+        }
+
+        $first = $value[0];
+        $last = $value[strlen($value) - 1];
+
+        if (($first === '"' || $first === "'") && $last === $first) {
+            return substr($value, 1, -1);
+        }
+
+        return null;
+    }
 }

tests/EnvTest.php

@@ -70,6 +70,30 @@ public function testEnvLoadsEmptyStringKeyword(): void
         $this->assertSame('empty', Env::get('EMPTY_VALUE'));
     }
 
+    public function testEnvGetCastCastsCommonValues(): void
+    {
+        $this->assertTrue(Env::getCast('FEATURE_ENABLED', null, true));
+        $this->assertFalse(Env::getCast('FEATURE_DISABLED', null, true));
+        $this->assertNull(Env::getCast('OPTIONAL_VALUE', 'fallback', true));
+        $this->assertSame('', Env::getCast('EMPTY_VALUE', 'fallback', true));
+        $this->assertSame('MyApp', Env::getCast('APP_NAME', null, true));
+        $this->assertSame('default', Env::getCast('NOT_DEFINED', 'default', true));
+    }
+
+    public function testEnvGetCastStripsWrappingQuotes(): void
+    {
+        unset($_ENV['CAST_QUOTED'], $_SERVER['CAST_QUOTED']);
+        putenv('CAST_QUOTED');
+        putenv('CAST_QUOTED="hello"');
+
+        try {
+            $this->assertSame('hello', Env::getCast('CAST_QUOTED', null, true));
+        } finally {
+            unset($_ENV['CAST_QUOTED'], $_SERVER['CAST_QUOTED']);
+            putenv('CAST_QUOTED');
+        }
+    }
+
     public function testEnvRemovesQuotes(): void
     {
         $this->assertSame('http://localhost:3000', Env::get('SSR_URL'));