Environment Variables

Kirby Helpers loads .env files with phpdotenv, so the file follows its syntax:

KIRBY_DEBUG=true
MAIL_FROM=noreply@example.com

Load the File in config.php

Load the file at the top of config.php, so the options below it can read its values. Env::load() takes the directory that holds the file. A second argument names a file other than .env.

Env::load() throws when the file is missing; where production sets its variables in the server environment, load it only when it exists:

use JohannSchopplich\Helpers\Env;

$root = dirname(__DIR__, 2);

if (is_file($root . '/.env')) {
    Env::load($root);
}

return [
    'debug' => env('KIRBY_DEBUG', false)
];

With the Composer install, Env and env() are autoloaded before Kirby reads config.php. A ZIP install loads with the plugins, after config.php – read values with $site->env() instead.

Read Values

env() reads a variable anywhere once the file is loaded – in config.php, templates, snippets, and plugins:

<?php $mailFrom = env('MAIL_FROM', 'hello@example.com') ?>

A missing variable returns the default, which can be a closure that runs only then. A variable set to an empty value returns '', not the default.

A variable already set in the server environment wins over the same name in the file. Loaded values are written to $_ENV and $_SERVER, not to getenv(), so a library that reads getenv() does not see them.

Value Parsing

Four spellings are parsed, in any letter case:

Numbers stay strings – PORT=8080 returns '8080', so cast it where you need an integer.

Load the File on First Use

Without Env::load() – as with a ZIP install – $site->env() loads the file on its first call, then reads like env():

<?php $mailFrom = $site->env('MAIL_FROM', 'hello@example.com') ?>

When the file is missing, it skips loading and returns the default, unless the server environment sets the variable.

env.path sets the directory – Kirby's base root when your site defines one, else the folder that holds site – and env.filename the file name, .env by default:

return [
    'johannschopplich.helpers' => [
        'env' => [
            'filename' => '.env.local'
        ]
    ]
];