Skip to content

Configuration

David Ciulla edited this page Nov 7, 2026 · 2 revisions

Configuration

Introduction

All Laravex configuration lives in two complementary layers:

  1. .env — environment-specific secrets and toggles (never committed to source control).
  2. config/*.exs — Elixir map files, one per concern (e.g. app.exs, database.exs, session.exs).

This mirrors the Laravel 13 convention precisely. The framework runtime (Laravex.Config.Repository) loads both layers at boot and merges them into a single in-memory store.


Environment Files

The .env File

Sensitive values such as APP_KEY, database credentials, and third-party secrets belong in .env. Copy the example to get started:

cp .env.example .env

The file uses a simple KEY=VALUE format. Inline comments are supported with #:

APP_NAME=Laravex
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://localhost:8000

Never commit .env to source control. It is listed in .gitignore by default.

Available Environment Variables

The following variables ship in .env.example:

Variable Default Purpose
APP_NAME Laravex Application display name
APP_ENV local Environment (local, production, testing)
APP_KEY (empty) Encryption key — run ./artisan key:generate
APP_DEBUG true Enable detailed error output
APP_URL http://localhost:8000 Base URL used by URL generation
APP_LOCALE en Default locale
APP_FALLBACK_LOCALE en Fallback locale
APP_FAKER_LOCALE en_US Locale for factory fake data
APP_MAINTENANCE_DRIVER file Maintenance mode driver
TRUSTED_PROXIES (empty) Comma-separated proxy IPs or *
TRUSTED_HOSTS (empty) Comma-separated allowed Host headers
BCRYPT_ROUNDS 12 Hashing cost factor
LOG_CHANNEL stack Primary log channel
LOG_LEVEL debug Minimum log level
DB_CONNECTION sqlite Database driver (sqlite, mysql/mariadb, pgsql/postgres)
DB_HOST / DB_PORT / DB_DATABASE / DB_USERNAME / DB_PASSWORD — Used by MySQL / PostgreSQL adapters
SESSION_DRIVER database Session storage (file, database, redis)
SESSION_LIFETIME 120 Session lifetime in minutes
SESSION_ENCRYPT false Encrypt session cookie values
BROADCAST_CONNECTION log Broadcasting backend (log, null, array, pubsub)
FILESYSTEM_DISK local Default filesystem disk (local, s3)
QUEUE_CONNECTION database Queue backend (sync, database, deferred, redis)
CACHE_STORE database Cache store (array, file, database, redis)
REDIS_HOST / REDIS_PORT / REDIS_PASSWORD 127.0.0.1 / 6379 Redis connection used by cache / session / queue
MAIL_MAILER log Mail transport (log, array, smtp)
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGION / AWS_BUCKET — S3 disk credentials

Tip: true, false, null, and empty in .env are automatically coerced to their Elixir equivalents (true, false, nil, "") by Laravex.Env.


Configuration Files

Location

Application config files live in config/ and have an .exs extension. Each file must return an Elixir map:

# config/app.exs
%{
  name: System.get_env("APP_NAME", "Laravex"),
  env: System.get_env("APP_ENV", "production"),
  debug: System.get_env("APP_DEBUG") in ["true", "1"],
  key: System.get_env("APP_KEY"),
  url: System.get_env("APP_URL", "http://localhost"),
  locale: System.get_env("APP_LOCALE", "en"),
  trusted_proxies: System.get_env("TRUSTED_PROXIES"),
  trusted_hosts: System.get_env("TRUSTED_HOSTS")
}

Mix Config vs. Laravex Config

Laravex deliberately separates its own config files from Mix's:

Files Purpose
config/config.exs, dev.exs, test.exs, prod.exs, runtime.exs Mix / OTP configuration — not loaded by Laravex
config/app.exs, config/database.exs, config/session.exs, … Laravex application config — loaded at runtime

This matches the Laravel 13 convention: framework config is decoupled from the build tool's config.

The following files are loaded automatically if present:

config/app.exs
config/auth.exs
config/cache.exs
config/database.exs
config/filesystems.exs
config/logging.exs
config/mail.exs
config/queue.exs
config/services.exs
config/session.exs

Any additional *.exs files in config/ are also loaded and merged.


Accessing Configuration

Use Laravex.Config.Repository.get/2 with dotted key notation anywhere in your application:

# Retrieve a value
Laravex.Config.Repository.get("app.name")
#=> "Laravex"

# Retrieve with a default
Laravex.Config.Repository.get("cache.ttl", 3600)

# Retrieve an entire config map
Laravex.Config.Repository.get("database")

# List all loaded config namespaces
Laravex.Config.Repository.files()
#=> ["app", "cache", "database", "session", ...]

# Access all configs at once
Laravex.Config.Repository.all()

The dotted key "file.key.nested" traverses the loaded map tree, supporting both string and atom keys at each level.


Caching Configuration

For production, cache all config files into a single binary term for faster boot:

./artisan config:cache    # writes bootstrap/cache/config.term
./artisan config:clear    # removes the cache and reloads from files

When a cache file exists at bootstrap/cache/config.term, Laravex loads it directly instead of evaluating each *.exs file.


Environment-Aware Values

Read environment variables in your config files using System.get_env/2 or the Laravex.Env helper:

# config/database.exs
%{
  default: System.get_env("DB_CONNECTION", "sqlite"),
  connections: %{
    sqlite: %{
      database: Path.join(File.cwd!(), "storage/database.sqlite")
    }
  }
}

Maintenance Mode

Put the application into maintenance mode with Artisan:

./artisan down --message="Deploying update" --retry=60 --secret=bypass-token

Laravex writes a JSON payload to storage/framework/down. The PreventRequestsDuringMaintenance middleware returns a 503 response to all requests until maintenance mode is lifted:

./artisan up

Requests that include ?secret=bypass-token bypass the maintenance check.


Trusted Proxies and Hosts

Trusted Proxies

Configure TRUSTED_PROXIES in .env or set app.trusted_proxies in config/app.exs. When a request arrives from a trusted proxy, Laravex honors X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host headers:

TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
# or trust all proxies (useful behind a load balancer you control):
TRUSTED_PROXIES=*

Trusted Hosts

Restrict which Host header values Laravex accepts. Leave empty to allow all hosts:

TRUSTED_HOSTS=myapp.com,*.myapp.com

The middleware returns 400 Bad Request for requests with an untrusted Host.

Clone this wiki locally