Configuration Overview
Tour the config directory, environment variables, and cache strategy.
.env first #
VelvetCMS leans on environment variables for secrets and env-specific toggles. The installer copies .env.example → .env, but you can override any key at runtime (Docker secrets, systemd, etc.). The most common knobs are below—jump to Environment & Secrets when you need deeper commentary or per-environment recommendations.
| Key | Effect |
|---|---|
APP_ENV |
Informational environment label used by commands (e.g., migrate warns if set to production). |
APP_DEBUG |
Enables verbose exception output (HTML+JSON stack traces). Always false in production. |
APP_URL |
Base URL injected into theme variables and link helpers. |
APP_NAME |
Appears in templates, CLI greetings, and meta tags. |
DB_CONNECTION, DB_DATABASE, DB_HOST, DB_USERNAME, DB_PASSWORD |
Configure the active database connection as defined in config/db.php. |
CACHE_DRIVER, CACHE_PREFIX |
Select cache backend (file, redis, …) and namespace keys per deployment. |
CONTENT_DRIVER |
Choose file, db, hybrid, or auto for the page pipeline. |
THEME |
Overrides config/theme.php’s active value so tenants can pick different themes. |
SESSION_* |
Control cookie name, lifetime, SameSite/Secure flags (see config/session.php). |
REDIS_* |
Host, port, password for Redis-backed cache/session drivers. |
Use install --force to regenerate .env if you need a clean slate, and never commit the file to VCS.
Config files #
Each file in config/*.php returns an array. The most relevant ones:
| File | Highlights |
|---|---|
app.php |
App name, URL, env, debug flag, timezone, locale, and service providers. |
cache.php |
Default driver plus per-driver settings (file path, Redis host/port/password). CACHE_DRIVER selects the key. |
content.php |
Default content driver (file, db, hybrid, auto) and Markdown parser settings—cache TTL, CommonMark extensions. |
db.php |
Connection definitions (sqlite/mysql/pgsql). Each reads from env vars so you can swap drivers easily. |
http.php |
Middleware aliases + global stack. Add your auth/logging middleware here. |
modules.php |
Discovery paths, explicit module map, and auto_discover toggle. |
session.php |
Cookie name, lifetime, SameSite & Secure settings. |
theme.php |
Single active key (overrides via THEME env). |
version.php |
Core version metadata (release date, stability) plus module metadata merged in at runtime. |
exceptions.php |
Slots for custom renderers/reporters bound to exception classes. |
Call config('app.name') anywhere to read values—the ConfigRepository keeps everything in memory after the first access.
Caching configuration #
velvet config:cache compiles every config file into storage/cache/config.php. Subsequent requests read that file directly, skipping directory traversal. Pair it with config:clear during deployments:
./velvet config:clear
./velvet config:cache
The cache file is just PHP, so OPcache keeps it in memory once loaded.
Custom config #
Drop any config/foo.php file and access it via config('foo.bar'). Remember to ship sane defaults via arrays, then let users override via .env. Modules commonly publish their own config file and merge it in during register().
Detecting changes #
- For environment changes, restart PHP-FPM or clear OPcache if necessary—
.envis read during bootstrap. - For config file edits in production, re-run
config:cache. In dev (with debug on) the repository re-reads files automatically.
With this mental map you know where to tweak VelvetCMS behavior without ever touching core code.