Configuration

Environment values live in .env files and are read through the generated Config class. The build turns every key into a typed method, so you never touch raw values at runtime.

The .env file

Values live in a .env file at the project root, written as KEY = value pairs. The framework ships a base .env.example that lists every supported key with a sensible default, so your .env only needs the values you actually change:

NAME        = "My App"
URL         = "https://example.com/"
DB_DATABASE = "myapp"
DB_USERNAME = "root"
DB_PASSWORD = ""

Every key becomes a typed method

During the build, each entry is turned into a typed getter on the generated Config class. The name is converted from constant case and the return type is inferred from the value — booleans get an is getter:

use Framework\System\Config;

Config::getName();       // "My App"  (string)
Config::getDbLogTime();  // 3         (int)
Config::isAuthActive();  // true      (bool)

URLs are special

Any key ending in URL becomes a path builder rather than a plain getter: it appends the parts you pass onto the base url, so you never join paths by hand. A specific url key falls back to the base URL when it is empty:

Config::getUrl();                 // https://example.com/
Config::getUrl("api", "users");   // https://example.com/api/users
Config::getFileUrl("avatars", 7); // https://example.com/files/avatars/7

Environments

Next to .env you can add one file per environment: .env.local, .env.production, .env.staging, and so on. The values in the matched file overwrite the ones in .env, which in turn overwrite the framework's .env.example defaults — so each layer only sets what it needs to change.

URL       = "https://myapp.com/"
DB_HOST   = "10.0.0.5"
DEBUG     = false

The right file is chosen automatically by matching the host of a *URL key against the host of the current request. Point .env.production's URL at myapp.com and it loads there.

The local environment

Local development uses the special local environment, which always exists. Add a .env.local whose URL points at your local host and it loads while you develop, overwriting .env like any other environment. When no file matches the current host you fall back to local as well:

URL   = "http://localhost:8080/"
DEBUG = true

Each environment also generates an is check — the local one is always present:

Config::isLocal();       // true while developing
Config::isProduction();  // true on myapp.com

Forcing an environment

On the command line there is no request URL to match — a deploy script, a migration, a cron. Set the ENV_FILENAME environment variable to load a specific file regardless of host:

# deployment / CI
ENV_FILENAME=.env.production ./framework migrate

How the files are read

Configs is what turns those files into the generated class. It reads the framework's .env.example first, then your .env, then the file matching the environment — each layer overwriting the last, which is why a .env.production only needs the values that differ.

use Framework\Core\Configs;

Configs::getEnvironment();    // the environment that matched
Configs::getEnvironments();   // every one that has a file
Configs::setFileName(".env.production");   // force one, before anything reads it

setFileName() is what migrate uses for its env-file argument, and the same idea as the ENV_FILENAME variable. During a build this class is also the builder that writes Config, so the typed getters and the files they read come from one place.

.env.example reference

Every key the framework understands, grouped by the sections of .env.example:

General

Application identity and the base url.

Database

MySQLi connection, encryption key and slow-query logging. See Database.

File

Where uploaded files are stored and served from. See Files & Storage.

Auth

JWT signing, token lifetimes and API access. See Authentication.

Email

Sending, templating, providers and cleanup. See Emails.

SMTP

Credentials for the built-in SMTP transport. See Email providers.

Mailjet

Mailjet transport and default contact list. See Email providers.

Mailgun

Mailgun transport key. See Email providers.

Mandrill

Mandrill transport key. See Email providers.

Send Grid

SendGrid transport key. See Email providers.

Mailchimp

Audience sync and campaign sending. See Email providers.

Notifications

Push notifications and their cleanup. See Notifications.

One Signal

OneSignal push provider credentials. See Notifications.

Google

Google OAuth credentials. See Providers.

Google Map

Google Maps provider. See Providers.

Microsoft

Microsoft OAuth client. See Providers.

Open AI

OpenAI API access. See Providers.

Ollama

Local Ollama server. See Providers.

Mercado Pago

MercadoPago checkout and webhooks. See Providers.

Redis

Redis cache toggle. See Providers.

Logs

Retention windows for each log type. See Logging.