feat: Introduced the fromOrDefault method to allow retrieving environment variables with a default value. (#3)

Author: gustavofreze

README.md

@@ -35,6 +35,16 @@ To create and work with environment variables, use the `from` method to get an i
 EnvironmentVariable::from(name: 'MY_VAR');
 ```
 
+To retrieve an environment variable with the option of providing a default value in case the variable does not exist,
+use the `fromOrDefault` method.
+
+If the environment variable is not found, the method will return the provided default value instead of throwing an
+exception.
+
+```php
+EnvironmentVariable::fromOrDefault(name: 'MY_VAR', defaultValueIfNotFound: 'default_value');
+```
+
 ### Conversions
 
 Once you have an instance of the environment variable, you can convert its value into various types.

phpunit.xml

@@ -6,6 +6,7 @@
          failOnRisky="true"
          failOnWarning="true"
          cacheDirectory=".phpunit.cache"
+         executionOrder="random"
          beStrictAboutOutputDuringTests="true">
 
     <source>

src/Environment.php

@@ -21,6 +21,15 @@ interface Environment
      */
     public static function from(string $name): Environment;
 
+    /**
+     * Retrieves an instance of the environment variable or uses a default value if not found.
+     *
+     * @param string $name The name of the environment variable.
+     * @param string|null $defaultValueIfNotFound The default value to use if the environment variable is not found.
+     * @return EnvironmentVariable The environment variable instance, either with the found value or the default.
+     */
+    public static function fromOrDefault(string $name, string $defaultValueIfNotFound = null): EnvironmentVariable;
+
     /**
      * Checks if the environment variable has a value. Values like `false`, `0`, and `-1` are valid and non-empty.
      *

src/EnvironmentVariable.php

@@ -22,6 +22,15 @@ public static function from(string $name): EnvironmentVariable
             : new EnvironmentVariable(value: $environmentVariable, variable: $name);
     }
 
+    public static function fromOrDefault(string $name, string $defaultValueIfNotFound = null): EnvironmentVariable
+    {
+        $environmentVariable = getenv($name);
+
+        return $environmentVariable === false
+            ? new EnvironmentVariable(value: (string)$defaultValueIfNotFound, variable: $name)
+            : new EnvironmentVariable(value: $environmentVariable, variable: $name);
+    }
+
     public function hasValue(): bool
     {
         return match (strtolower(trim($this->value))) {

tests/EnvironmentVariableTest.php

@@ -50,6 +50,43 @@ public function testConvertToBoolean(mixed $value, string $variable, bool $expec
         self::assertEquals($expected, $actual);
     }
 
+    public function testFromOrDefaultWithDefaultValue(): void
+    {
+        /** @Given that the environment variable 'NON_EXISTENT_MY_VAR' does not exist */
+        $variable = 'NON_EXISTENT_MY_VAR';
+
+        /** @When I try to get the value of the environment variable with a default value */
+        $actual = EnvironmentVariable::fromOrDefault(name: $variable, defaultValueIfNotFound: '0');
+
+        /** @Then the result should match the default value */
+        self::assertEquals(0, $actual->toInteger());
+    }
+
+    public function testFromOrDefaultWithExistingVariable(): void
+    {
+        /** @Given that the environment variable 'MY_VAR' exists with the value 'existing_value' */
+        putenv(sprintf('%s=%s', 'MY_VAR', 'existing_value'));
+
+        /** @When I try to get the value of the environment variable */
+        $actual = EnvironmentVariable::fromOrDefault(name: 'MY_VAR', defaultValueIfNotFound: 'default_value');
+
+        /** @Then the result should match the existing value */
+        self::assertEquals('existing_value', $actual->toString());
+    }
+
+    public function testFromOrDefaultWhenVariableIsMissingAndNoDefault(): void
+    {
+        /** @Given that the environment variable 'NON_EXISTENT_VAR' does not exist */
+        $variable = 'NON_EXISTENT_VAR';
+
+        /** @When I try to get the value of the missing environment variable without a default value */
+        $actual = EnvironmentVariable::fromOrDefault(name: $variable);
+
+        /** @Then the result should be no value */
+        self::assertEmpty($actual->toString());
+        self::assertFalse($actual->hasValue());
+    }
+
     #[DataProvider('hasValueDataProvider')]
     public function testHasValue(mixed $value, string $variable): void
     {
@@ -225,15 +262,15 @@ public static function hasValueDataProvider(): array
     public static function hasNoValueDataProvider(): array
     {
         return [
-            'Null value'        => [
+            'Null value'              => [
                 'value'    => null,
                 'variable' => 'NULL_VALUE'
             ],
-            'Empty string'      => [
+            'Empty string'            => [
                 'value'    => '',
                 'variable' => 'EMPTY_STRING'
             ],
-            'String null value' => [
+            'String null value'       => [
                 'value'    => 'NULL',
                 'variable' => 'NULL_VALUE'
             ],