DEV Community: Franky Braem

Configure your application using PHP dotenv

Franky Braem — Fri, 18 Mar 2022 20:58:16 +0000

PHP dotenv

PHP dotenv loads environment variables from .env to getenv(), $_ENV and $_SERVER automagically.

Avoid storing sensitive data in your code. Instead, use the environment or a configuration file. Storing config in the environment is the third factor of The Twelve-Factor App.

composer require vlucas/phpdotenv

Configuration class

Create a wrapper class Configuration to hide the dotenv implementation. Add factory methods to create a configuration from a file and from a string.

use Dotenv\Dotenv;
use Dotenv\Loader\Loader;
use Dotenv\Parser\Parser;
use Dotenv\Repository\RepositoryBuilder;
use Dotenv\Store\StringStore;

class Configuration
{
    public function __construct(
        private Dotenv $env
    ) {
    }

    /**
     * Load configuration from a file.
     *
     * @param string $path
     * @param string $file
     * @return static
     */
    public static function createFromFile(string $path, string $file): self
    {
        $env = Dotenv::createImmutable($path, $file);
        $env->load();
        return new self($env);
    }

    /**
     * Load configuration from a string.
     *
     * @param string $content
     * @return static
     */
    public static function createFromString(string $content): self
    {
        $repository = RepositoryBuilder::createWithDefaultAdapters()->immutable()->make();
        $env = new Dotenv(new StringStore($content), new Parser(), new Loader(), $repository);
        $env->load();
        return new self($env);
    }

Dotenv does not provide a direct method to load from a string. There is a parse method, but that method only returns the loaded variables. When you want to add validation, you need a Dotenv instance. A StringStore is available and createFromString hides the complexity to create and load a Dotenv from a string. Probably createFromString will not be used in production code, but it can be useful in unit tests.

After calling load, all variables will be available in $_SERVER, $_ENV or getenv(). Using these variables all over the place in the code is not a good idea. What happens when a name of a variable needs to change? The content of these variables are not typesafe. Make untyped content as soon as possible typed. IDE's and static code analyzers will make it possible to find errors before the code is released to production. And as an extra, refactoring code will be a lot easier.

A sample: DatabaseConfiguration.

First make a contract between the Configuration class and the several configurations: the Configurable interface:

<?php
declare(strict_types=1);

use Dotenv\Dotenv;

/**
 * Interface Configurable
 */
interface Configurable
{
    public static function createFromVariables(array $variables): self;

    public static function validate(Dotenv $env): void;
}

A database configuration needs a DSN, a user and a password. This class will be the only one that uses the DB_DSN, DB_USER and DB_PASSWORD strings.

<?php
declare(strict_types=1);

use Dotenv\Dotenv;

/**
 * Class DatabaseConfiguration
 */
class DatabaseConfiguration implements Configurable
{
    public function __construct(
        private string $dsn,
        private string $user,
        private string $password
    ) {
    }

    public function getDsn(): string
    {
        return $this->dsn;
    }

    public function getUser(): string
    {
        return $this->user;
    }

    public function getPassword(): string
    {
        return $this->password;
    }

    public static function createFromVariables(array $variables): self
    {
        return new self(
            $variables['DB_DSN'],
            $variables['DB_USER'],
            $variables['DB_PASSWORD']
        );
    }

    public static function validate(Dotenv $env): void
    {
        $env->required([
            'DB_DSN',
            'DB_USER',
            'DB_PASSWORD',
        ]);
    }

    public function createConnection(): PDO
    {
        return new PDO($this->dsn, $this->user, $this->password); 
    }
}

The DatabaseConfiguration is created with a factory method in Configuration:

    public function getDatabaseConfiguration(): DatabaseConfiguration
    {
        DatabaseConfiguration::validate($this->env);
        return DatabaseConfiguration::createFromVariables($_SERVER);
    }

Testing

Testing the configuration is possible using the createFromString method.

it('can create a DatabaseConfiguration', function () {
    $configuration = Configuration::createFromString("DB_DSN=<your_dsn>\nDB_USER=test\nDB_PASSWORD=test1234");
    $dbConfiguration = $configuration->getDatabaseConfiguration();
    expect($dbConfiguration->getDsn())
        ->toBe('<your_dsn>')
    ;
    expect($dbConfiguration->getUser())
        ->toBe('test')
    ;
    expect($dbConfiguration->getDsn())
        ->toBe('test1234')
    ;
});

it('detect a missing password in DatabaseConfiguration', function () {
    $configuration = Configuration::createFromString("DB_DSN=<your_dsn>\nDB_USER=test");
    $configuration->getDatabaseConfiguration();
})
    ->expectException(ValidationException::class)
;

These tests are written with PestPHP.

Dependency injection container

getenv and putenv are not thread safe. I've experienced that when running multiple tests. To be sure that only one instance is created of the Configuration class, a dependency injection container can be used.

Symfony routing with attributes (standalone)

Franky Braem — Sun, 06 Feb 2022 13:01:54 +0000

Attributes

As of PHP 8, PHP Attributes are available. Attributes can be used to add metadata to classes, methods, functions, parameters, properties and class constants. The advantage of using attributes, is that you can keep the metadata close to the code.

Symfony routing

As of version 6, the Symfony routing package supports Attributes. If there is one place where metadata is interesting to use, it is routing. In previous versions of PHP, this could be solved using comments (annotations). With attributes, the dependency on doctrine/annotations is not needed anymore.

I'm using Symfony router in my own framework and I also wanted to take advantage of using attributes. Each route is linked to an action class. Attributes applied to the action class will define how it can be reached. Because I don't use the Symfony framework, I needed to figure out a way to load the routes from the action classes.

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Symfony\Component\Routing\Annotation\Route;

#[Route(
    path: '/trainings/{id}',
    name: 'trainings.get',
    requirements: [
        'id' => '\d+'
    ]
)]
final class GetTrainingAction
{
    public function __invoke(Request $request, Response $response, array $args): Response
    {
    }
}

Symfony routing provides several ways of loading routes. There are Loaders and the one we particularly need is the AnnotationClassLoader. It's an abstract class, so we need to create a new class that derives from it. We need to define an implementation for the configureRoute method.

class RouteClassLoader extends AnnotationClassLoader
{
    protected function configureRoute(
        Route $route,
        \ReflectionClass $class,
        \ReflectionMethod $method,
        object $annot
    ) {
        $route->setDefault('_action', $class);
    }
};

The configureRoute can be used to add some configuration to the route. In our case we set _action to the class that is currently loaded. This class is a reflection to our action class GetTrainingAction. In my framework, the action class always implements an invoke method, so we can ignore $method here.

Now we can load the action class into our route collection:

    $loader = new RouteClassLoader();
    $collection = new RouteCollection();
    $collection->addCollection($loader->load(GetTrainingAction::class));

In the Route middleware (PSR-15), we try to match the route. When a match is found the Reflection class will be added as attribute to the request.

    public function __construct(
        private RouteCollection $routes
    ) {
    }

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $symfonyRequest = (new HttpFoundationFactory())->createRequest($request);
        $context = new RequestContext();
        $context->fromRequest($symfonyRequest);

        $matcher = new UrlMatcher($this->routes, $context);
        try {
            $parameters = $matcher->matchRequest($symfonyRequest);
            $route = $parameters['_route'] ?? null;
            unset($parameters['_route']);
            $action = $parameters['_action'] ?? null;
            unset($parameters['_action']);
            $request = $request
                ->withAttribute('kwai.route', $route)
                ->withAttribute('kwai.action', $action)
                ->withAttribute('kwai.action.args', $parameters)
            ;
        } catch (\Exception $e) {
            throw new RouteException(message: 'Could not find a route', previous: $e);
        }
        return $handler->handle($request);
    }

The actual execution of the action is done in the RequestHandlerMiddleware

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $action = $request->getAttribute('kwai.action');

        if ($action instanceof \ReflectionClass) {
            try {
                $callableAction = $action->newInstance();
            } catch (ReflectionException $e) {
                throw new RuntimeException(
                    message: "Could not create an instance of the action class: $action",
                    previous: $e
                );
            }
        } else {
            throw new \RuntimeException('Invalid request handler set');
        }
        return $callableAction($request, $this->response, $request->getAttribute('kwai.action.args'));
    }