Load at boot

The store starts empty. envless/env has to fetch the ciphertext and decrypt it before Env::get() returns anything, and reading a variable before that throws NotLoadedException:

Envless env is not loaded yet. Call Envless\Env\Env::load() first, or prepend vendor/envless/env/register.php.

Installing the package loads nothing by itself. There are two ways to make sure the load has happened before your code reads a variable.

Call Env::load() at the top of your entry point#

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

use Envless\Env\Env;

$record = Env::load();
$debug = Env::boolean('APP_DEBUG');

Env::load() returns a plain array<string, string> of every decrypted value, a copy you own and may serialise. It is memoised for the life of the PHP process: later calls return the same array without touching the disk or the network. A load that throws is not memoised, so the next call tries again.

Or prepend register.php#

vendor/envless/env/register.php includes Composer's autoloader and calls Env::load(). Point PHP's auto_prepend_file at it and every script is loaded before its first line runs, with no change to your code.

auto_prepend_file = /var/www/app/vendor/envless/env/register.php

php -d auto_prepend_file=vendor/envless/env/register.php bin/worker.php

If the load fails, the prepended file throws the same LoadException that Env::load() would, so a misconfigured process stops before it serves a request with a hole in its configuration. PHP-FPM and plain PHP shows the pool and Apache settings.

The credentials it reads#

Each name is read from $_ENV, then $_SERVER, then getenv(), so a variable set by your shell, your container, an FPM pool or an Apache SetEnv is found wherever PHP put it. A name that starts with HTTP_ is the exception: under PHP-FPM and Apache those slots also carry the request's headers, so for such a name only $_ENV and the process's own environment count, and a client cannot override a variable by sending a header. Get the machine key from Keys in the dashboard and the raw workspace key from machine access. With ENVLESS_TOKEN unset, the loader falls back to the token envless login stored on this machine, and since that is a session token it fails with ENVLESS_TOKEN must be a machine key (ev_sk_…). Create one in the Envless dashboard. The standalone loader is always machine authenticated.

The .envless file is the one envless link writes into your project folder. The loader reads it from the current working directory first and then from your Composer project root, the folder that holds vendor/. That second place matters for PHP: PHP-FPM, Apache and php -S run a request with public/ as the working directory, so a .envless next to composer.json is still found.

What a load does#

The process environment#

Decrypted values are written into $_ENV, $_SERVER and putenv() without overwriting anything already set in any of them, so a variable from your shell or platform wins there, the way vlucas/phpdotenv behaves by default. Laravel's env(), Symfony's %env()% and libraries that call getenv() keep working. Env::get() always hands back the Envless value.

Names that change how a process or its children execute code are never written into the process environment: NODE_OPTIONS, NODE_PATH, NODE_REPL_EXTERNAL_MODULE, ELECTRON_RUN_AS_NODE, LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH, DYLD_FRAMEWORK_PATH, PATH, BUN_INSPECT, BUN_INSPECT_CONNECT_TO, RUBYOPT, RUBYLIB, BUNDLE_GEMFILE, GEM_HOME, GEM_PATH, PYTHONPATH, PYTHONHOME, PYTHONSTARTUP, PYTHONUSERBASE, PHPRC, PHP_INI_SCAN_DIR, ENVLESS_CLIENT_ENV and ENVLESS_INJECTED, whatever their case. PHPRC and PHP_INI_SCAN_DIR matter most here: either one would point a child php at another php.ini, and an ini with auto_prepend_file turns a variable into code. They are still decrypted and readable through Env::get(), and the loader names each one it skipped in a warning: on standard error in the CLI, and through error_log() under PHP-FPM and Apache.

Inside envless run#

When envless run starts your process, the CLI has already decrypted the values into the environment and written a manifest, ENVLESS_INJECTED, naming each variable with its type and visibility. The first time anything reads the store, envless/env adopts those names straight from the environment: no ENVLESS_TOKEN, no key and no request.

envless run --env production -- php artisan queue:work

Env::load() then returns the injected values without fetching. Env::load(revalidate: true) deliberately escapes them and runs a real load, so it needs a machine key like any standalone load.

Reloading#

Env::load(revalidate: true) skips the memo and the cache, fetches again, and replaces the values Env::get() reads. In the process environment, a name a previous load wrote is updated, a name that has disappeared is removed, and a name that was already set from somewhere else is still left alone. Under PHP-FPM every request is a new load anyway, so reloading only matters in long-running workers:

pcntl_async_signals(true);
pcntl_signal(SIGHUP, static function (): void {
    Envless\Env\Env::load(revalidate: true);
});

The cache#

After a fetch, the ciphertext is written to ~/.envless/cache/, one file per workspace, product, project and environment, in the same format @goenvless/env writes, so a Node, a Python and a PHP app on one machine share it. Only ciphertext is stored, never a decrypted value, in a folder with mode 0700 and files with mode 0600. Writing it is best effort: a failed write never fails the load. An entry older than 15 minutes, stamped in the future or written under another workspace is ignored. envless cache clear empties it. Caching and reloads covers the shared rules.

Two rules are PHP's own, because PHP-FPM starts every request from scratch:

A refused key, a missing environment or any other 4xx is never covered by the old values, and neither is Env::load(revalidate: true), so revoking a machine key still stops a site at its next load.

What a request costs#

Use ENVLESS_KEY in production. The passphrase is fine for a CLI script or a long-running worker that loads once, and expensive for anything that loads per request.

Servers, workers and scripts#

When a load fails#

Every failure throws Envless\Env\Exception\LoadException, with the API or network error as its previous exception where there is one. The store and the process environment are left as they were, so after a failed reload Env::get() keeps the values of the last load that worked.

A build step that runs your code without secrets, such as composer install running package:discover, should not load at all. Env::isConfigured() is true only when a machine key is available, in ENVLESS_TOKEN or the CLI config, or envless run injected the values, so guard the load with it. The session token envless login stores does not count, so a laptop logged in to the CLI still boots from .env:

use Envless\Env\Env;

if (Env::isConfigured()) {
    Env::load();
}