EnvMapper
Reading environment variables is a common part of most applications. However, it's often done in an ad-hoc and unsafe
way, by calling getenv()
or reading $_ENV
from an arbitrary place in code. That means error handling, missing-value
handling, default values, etc. are scattered about the code base.
This library changes that. It allows you to map environment variables into arbitrary classed objects extremely fast, which allows using the class definition itself for default handling, type safety, etc. That class can then be registered in your dependency injection container to become automatically available to any service.
Usage
EnvMapper has almost no configuration. Everything is just the class.
// Define the class.
class DbSettings
{
public function __construct(
// Loads the DB_USER env var.
public readonly string $dbUser,
// Loads the DB_PASS env var.
public readonly string $dbPass,
// Loads the DB_HOST env var.
public readonly string $dbHost,
// Loads the DB_PORT env var.
public readonly int $dbPort,
// Loads the DB_NAME env var.
public readonly string $dbName,
) {}
}
$mapper = new Crell\EnvMapper\EnvMapper();
$db = $mapper->map(DbSettings::class);
$db
is now an instance of DbSettings
with all five properties populated from the environment, if defined. That object
may now be used anywhere, passed into a constructor, or whatever. Because its properties are all readonly
, you
can rest assured that no service using this object will be able to modify it.
You can use any class you'd like, however. All that matters is the defined properties (defined via constructor promotion or not). The properties may be whatever visibility you like, and you may include whatever methods you'd like.
Name mapping and default values
EnvMapper will convert the name of the property into UPPER_CASE
style, which is the style typically used
for environment variables. It will then look for an environment variable by that name and assign it to that property.
That means you may use lowerCamel
or snake_case
for object properties. Both will work fine.
If no environment variable is found, but the property has a default value set in the class definition, that default value will be used. If there is no default value, it will be left uninitialized.
Alternatively, you may set requireValues: true
in the map()
call. If requireValues
is set, then a missing property will instead
throw a MissingEnvValue
exception.
class MissingStuff
{
public function __construct(
public readonly string $notSet,
) {}
}
// This will throw a MissingEnvValue exception unless there is a NOT_SET env var defined.
$mapper->map(MissingStuff::class, requireValues: true);
Type enforcement
Environment variables are always strings, but you may know out-of-band that they are supposed to be an int
or float
.
EnvMapper will automatically cast int-like values (like "5" or "42") to integers, and float-like values (like "3.14") to
floats, so that they will safely assign to the typed properties on the object.
If a property is typed bool
, then the values "1", "true", "yes", and "on" (in any case) will evaluate to true
. Anything
else will evaluate to false.
If a value cannot be assigned (for instance, if the DB_PORT
environment variable was set to "any"
), then a TypeMismatch
exception will be thrown.
dot-env compatibility
EnvMapper reads values from $_ENV
by default. If you are using a library that reads .env
files into the environment,
it should work fine with EnvMapper provided it populates $_ENV
. EnvMapper does not use getenv()
as it is much slower.
Note that your variables_order in PHP needs to be set to include E
, for Environment,
in order for $_ENV
to be populated. If it is not, $_ENV
will be empty. If you cannot configure your server to populate
$_ENV
, and you cannot switch to a non-broken server, as a fallback you can pass the return of getenv()
to the source
parameter, like so:
$mapper->map(Environment::class, source: getenv());
Common patterns
Registering with a DI Container
The recommended way to use EnvMapper
is to wire it into your Dependency Injection Container, preferably one that
supports auto-wiring. For example, in a Laravel Service Provider you could do this:
namespace App\Providers;
use App\Environment;
use Crell\EnvMapper\EnvMapper;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\ServiceProvider;
class EnvMapperServiceProvider extends ServiceProvider
{
// The EnvMapper has no constructor arguments, so registering it is simple.
public $singletons = [
EnvMapper::class => EnvMapper::class,
];
public function register(): void
{
// When the Environment class is requested, it will be loaded lazily out of the env vars by the mapper.
// Because it's a singleton, the object will be automatically cached.
$this->app->singleton(Environment::class, fn(Application $app) => $app[EnvMapper::class]->map(Environment::class));
}
}
In Symfony, you could implement the same configuration in services.yaml
:
services:
Crell\EnvMapper\EnvMapper: ~
App\Environment:
factory: ['@Crell\EnvMapper\EnvMapper', 'map']
arguments: ['App\Environment']
Now, any service may simply declare a constructor argument of type Environment
and the container will automatically
instantiate and inject the object as needed.
Testing
The key reason to use a central environment variable mapper is to make testing easier. Reading the environment directly from each service is a global dependency, which makes testing more difficult. Instead, making a dedicated environment class an injectable service (as in the example above) means any service that uses it may trivially be passed a manually created version.
class AService
{
public function __construct(private readonly AwsSettings $settings) {}
// ...
}
class AServiceTest extends TestCase
{
public function testSomething(): void
$awsSettings = new AwsSettings(awsKey: 'fake', awsSecret: 'fake');
$s = new Something($awsSettings);
// ...
}
}
Multiple environment objects
Any environment variables that are set but not present in the specified class will be ignored. That means it's trivially easy to load different variables into different classes. For example:
class DbSettings
{
public function __construct(
public readonly string $dbUser,
public readonly string $dbPass,
public readonly string $dbHost,
public readonly int $dbPort,
public readonly string $dbName,
) {}
}
class AwsSettings
{
public function __construct(
public readonly string $awsKey,
public readonly string $awsSecret,
) {}
}
// Laravel version.
class EnvMapperServiceProvider extends ServiceProvider
{
public function register(): void
{
$this->app->singleton(DbSettings::class, fn(Application $app) => $app[EnvMapper::class]->map(DbSettings::class));
$this->app->singleton(AwsSettings::class, fn(Application $app) => $app[EnvMapper::class]->map(AwsSettings::class));
}
}
# Symfony version
services:
Crell\EnvMapper\EnvMapper: ~
App\DbSettings:
factory: ['@Crell\EnvMapper\EnvMapper', 'map']
arguments: ['App\DbSettings']
App\AwsSettings:
factory: ['@Crell\EnvMapper\EnvMapper', 'map']
arguments: ['App\AwsSettings']
Advanced usage
EnvMapper is designed to be lightweight and fast. For that reason, its feature set is deliberately limited.
However, there are cases you may wish to have a more complex environment setup. For instance, you may want to rename properties more freely, nest related properties inside sub-objects, or map comma-delimited environment variables into an array. EnvMapper is not designed to handle that.
However, its sibling project Crell/Serde
can do so easily. Serde is a general
purpose serialization library, but you can easily feed it $_ENV
as an array to deserialize from into an object. That
gives you access to all of Serde's capability to rename, collect, nest, and otherwise translate data as it's being
deserialized into an object. The basic workflow is the same, and registration in your service container is nearly
identical.
$serde = new SerdeCommon();
$env = $serde->deserialize($_ENV, from: 'array', to: Environment::class);
Using Serde will be somewhat slower than using EnvMapper, but both are still very fast and suitable for almost any application.
See the Serde documentation for all of its various options.
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email larry at garfieldtech dot com instead of using the issue tracker.
Credits
License
The Lesser GPL version 3 or later. Please see License File for more information.