Built-in dotenv configuration support (.env)

[clue]

Here's a common excerpt from our current database documentation (https://framework-x.org/docs/integrations/database/):

$credentials = 'alice:secret@localhost/bookstore?idle=0.001';
$db = (new React\MySQL\Factory())->createLazyConnection($credentials);

$app->get('/book/{isbn}', new Acme\Todo\BookLookupController($db));

In any production use case you wouldn't usually want to hard-code your DB login credentials and instead use some form of external configuration. In many cases, this means using environment variables or loading from a .env file, e.g. using vlucas/phpdotenv:

(Dotenv\Dotenv::createImmutable(dirname(__DIR__)))->load();
$factory = new Factory();
$db = $factory->createLazyConnection($_ENV['DB_URI'] . '?idle=0.001');

$app->get('/book/{isbn}', new Acme\Todo\BookLookupController($db));

Together with built-in DI container (#95, #96, #97), this could look something like this:

(Dotenv\Dotenv::createImmutable(dirname(__DIR__)))->load();

$container = new FrameworkX\Container([
    React\MySQL\ConnectionInterface::class => function () {
        $credentials = $_ENV['DB_URI'] . '?idle=0.001';
        return (new React\MySQL\Factory())->createLazyConnection($credentials);
    }
]);

$app = new FrameworkX\App($container);

$app->get('/book/{isbn}', Acme\Todo\BookLookupController::class);

By leveraging autowiring from the DI container (#97), we could also wrap the environment variables in an object like this:

$container = new FrameworkX\Container([
    stdClass::class => function () {
        (Dotenv\Dotenv::createImmutable(dirname(__DIR__)))->load();
        return (object) $_ENV;
    },
    React\MySQL\ConnectionInterface::class => function (stdClass $env) {
        $credentials = $env->DB_URI . '?idle=0.001';
        return (new React\MySQL\Factory())->createLazyConnection($credentials);
    }
]);

$app = new FrameworkX\App($container);

$app->get('/book/{isbn}', Acme\Todo\BookLookupController::class);

So far, all of this is already supported and the above snippet should work exactly as-is.

Given this is all fairly standard, at this point, I wonder if it makes sense to integrate some built-in dotenv support into X?

In the future, we may potentially also support some kind of naming convention for the DI container to automatically inject environment variables with proper type checks like this:

$container = new FrameworkX\Container([
    React\MySQL\ConnectionInterface::class => function (string $_ENV_DB_URI, ?float $_ENV_DB_IDLE) {
        $credentials = $_ENV_DB_URI . '?idle=' . ($_ENV_DB_IDLE ?? 0.001);
        return (new React\MySQL\Factory())->createLazyConnection($credentials);
    }
]);

$app = new FrameworkX\App($container);

$app->get('/book/{isbn}', Acme\Todo\BookLookupController::class);

Any thoughts/input on this?

[pfk84]

Great topic! Although I'm using phpdotenv as well, I'd prefer having something directly integrated into the framework - mainly to encourage using .env files. Also dig the type checks!

[clue]

By leveraging autowiring from the DI container (#97), we could also wrap the environment variables in an object like this:

$container = new FrameworkX\Container([
    stdClass::class => function () {
        (Dotenv\Dotenv::createImmutable(dirname(__DIR__)))->load();
        return (object) $_ENV;
    },
    React\MySQL\ConnectionInterface::class => function (stdClass $env) {
        $credentials = $env->DB_URI . '?idle=0.001';
        return (new React\MySQL\Factory())->createLazyConnection($credentials);
    }
]);

$app = new FrameworkX\App($container);

$app->get('/book/{isbn}', Acme\Todo\BookLookupController::class);

Quick progress update: I've looked into creating a built-in Env class that could be used like a stdClass, but I'm not particularly happy with this design for a number of reasons.

In particular, it requires users to specifically target this class name in their code which causes additional coupling. On top of this, it offers yet another API to work with environment variables next to getenv(), $_ENV and $_SERVER which already exist. Even if reading from the environment is certainly the main use case, it's tempting to also expect this to work for writing to the environment (again, should this be putenv() or $_ENV or $_SERVER?). Should we also support casting the environment to an array (again, we already have such global arrays) and should we provide convenience APIs such as count($env), etc..

Overall, I think this is only going to complicate things longer-term instead of making it easier (see motto "make easy things easy and hard things possible"). As such, I don't think how this should be implemented here.

[clue]

In the future, we may potentially also support some kind of naming convention for the DI container to automatically inject environment variables with proper type checks like this […]:

I think this is the way to go here as it neatly integrated with the built-in container and provides a clear, consistent API to access individual environment variables.

The idea is to start with a naming convention that all environment variables must be uppercase and may only target string values initially. Environment variables would be loaded automatically from the environment and a .env (dotenv) file if present. This way, we don't have to come up with arbitrary naming conventions and can reference environment variables by their name like this:

$container = new FrameworkX\Container([
    React\MySQL\ConnectionInterface::class => function (string $DB_URI, string $DB_IDLE) {
        $credentials = $DB_URI . '?idle=' . $DB_IDLE;
        return (new React\MySQL\Factory())->createLazyConnection($credentials);
    }
]);

As a next step, we should support optional environment variables that accept default values like this:

$container = new FrameworkX\Container([
    React\MySQL\ConnectionInterface::class => function (string $DB_URI, ?string $DB_IDLE = null) {
        $credentials = $DB_URI . ($DB_IDLE !== null ? '?idle=' . $DB_IDLE : '');
        return (new React\MySQL\Factory())->createLazyConnection($credentials);
    }
]);

As a future step, we may as well support automatic type casting to int, bool and float if the values match the respective type:

$container = new FrameworkX\Container([
    React\MySQL\ConnectionInterface::class => function (string $DB_URI, float $DB_IDLE = 0.001) {
        $credentials = $DB_URI . '?idle=' . $DB_IDLE;
        return (new React\MySQL\Factory())->createLazyConnection($credentials);
    }
]);

[clue]

Major progress update now that #184, #183, #182, #181, #180, #179, #178 have been merged 🎉 You may now reference environment variables from within your DI container configuration like this:

<?php

require __DIR__ . '/../vendor/autoload.php';

$container = new FrameworkX\Container([
    React\MySQL\ConnectionInterface::class => function (string $DB_HOST = 'localhost', string $DB_USER = 'root', string $DB_PASS = '', string $DB_NAME = 'acme') {
        // connect to database defined in optional $DB_* environment variables
        $uri = 'mysql://' . $DB_USER . ':' . rawurlencode($DB_PASS) . '@' . $DB_HOST . '/' . $DB_NAME . '?idle=0.001';
        return (new React\MySQL\Factory())->createLazyConnection($uri);
    }
]);

$app = new FrameworkX\App($container);

// …

Announced today via https://twitter.com/x_framework/status/1554810199973691396. See also https://framework-x.org/docs/best-practices/controllers/#container-configuration for documentation.

Outstanding features include loading variables from a dotenv file (.env) and possible data type conversions, e.g. for int values.

[clue]

Note there's ongoing discussion about best practices and concerns regarding using environment variables for secrets (passwords, keys, etc.) as discussed in https://twitter.com/sascha_egerer/status/1554841859008118786. As a starting point see also:

• https://stackoverflow.com/questions/12461484/is-it-secure-to-store-passwords-as-environment-variables-rather-than-as-plain-t
• https://security.stackexchange.com/questions/197784/is-it-unsafe-to-use-environmental-variables-for-secret-data
• https://blog.diogomonica.com//2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/
• Loads more…

I don't think there's clear consensus at the moment, but I'd love to help promote best practices. Perhaps we can add some remarks regarding secrets in our documentation? Any input would be much appreciated.