Config and Env Classes

Table of contents

  1. Overview
  2. Environment Configuration
  3. Env Utility
  4. Config Utility
  5. Best Practices
  6. Debugging
  7. Conclusion


1. Overview Table of Contents

We use two classes called Config and Env to manage configuration files and environmental variables. These classes are discussed in detail below.


2. Environment Configuration Table of Contents

This file controls application behavior across development, staging, and production environments. Values are loaded at runtime and influence logging, database connections, security policies, queues, mail, and frontend tooling.


🔧 Application Environment

DEBUG=true
LOGGING="debug"
APP_ENV=local

Controls overall runtime behavior.

DEBUG

Enables detailed error output and verbose logging when set to true. Should be false in production.

LOGGING

Sets the minimum PSR-3 severity level written to logs (debug, info, notice, warning, error, etc). Messages below this threshold are ignored.

APP_ENV

Indicates the current environment (local, staging, production). Used for environment-specific behavior.


🌐 Application Identity & Routing

APP_DOMAIN='http://localhost:8000/'
SITE_TITLE='My App'
MENU_BRAND='My Brand'

DEFAULT_CONTROLLER=Home
DEFAULT_LAYOUT=default

Defines application URLs and UI defaults.

  • APP_DOMAIN – Base application URL
  • SITE_TITLE – Default browser title
  • MENU_BRAND – Branding text shown in navigation
  • DEFAULT_CONTROLLER – Controller used when no route is specified
  • DEFAULT_LAYOUT – Default layout template


🔐 Security & Sessions

APP_KEY=
CURRENT_USER_SESSION_NAME=
REMEMBER_ME_COOKIE_NAME=
REMEMBER_ME_COOKIE_EXPIRY=2592000

Authentication and session configuration.

  • APP_KEY – Application encryption key
  • CURRENT_USER_SESSION_NAME – Session identifier for logged-in users
  • REMEMBER_ME_COOKIE_NAME – Persistent login cookie name
  • REMEMBER_ME_COOKIE_EXPIRY – Cookie lifetime (seconds)


🗄 Database Configuration

DB_CONNECTION=sqlite
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=database/database.sqlite
DB_USER=
DB_PASSWORD=
DB_LOG_PARAMS=full

Controls database connectivity and query logging.

  • DB_CONNECTION – sqlite, mysql, or mariadb
  • DB_HOST / DB_PORT – MySQL connection details
  • DB_DATABASE – Database name or SQLite path
  • DB_USER / DB_PASSWORD – Credentials
  • DB_LOG_PARAMS

Controls parameter logging:

  • none → only parameter count/type
  • masked → redacted values
  • full → full parameters (dev only)
  • This integrates with your logging system to prevent sensitive data leakage.


🔑 Password Policy

PW_LOWER_CHAR=true
PW_UPPER_CHAR=true
PW_NUM_CHAR=true
PW_SPECIAL_CHAR=true
PW_MIN_LENGTH=12
PW_MAX_LENGTH=30
SET_PW_MIN_LENGTH=true
SET_PW_MAX_LENGTH=true

Defines password complexity requirements.

Supports:

  • lowercase
  • uppercase
  • numbers
  • special characters
  • configurable minimum and maximum lengths

These values are also exposed to Vite for frontend validation.


🚫 Login Protection

MAX_LOGIN_ATTEMPTS=100

Maximum allowed login attempts before lockout.


⏰ Localization

TIME_ZONE='America/New_York'
LOCALE='en'

Sets application timezone and locale.


🎨 Console Styling

BACKGROUND_COLOR='green'
TEXT_COLOR='light-grey'

Used by console helpers for visual output formatting.


✉ Mail Configuration

MAILER_DSN=smtp://username:password@smtp.mailtrap.io:2525
MAIL_FROM_ADDRESS=no-reply@chappyphp.test
MAIL_FROM_NAME="ChappyPHP Framework"

SMTP configuration for outgoing mail.

Supports Symfony Mailer DSN format.


📬 Queue / Job Dispatch

QUEUE_DRIVER=database
MAX_ATTEMPTS=3
REDIS_HOST='127.0.0.1'
REDIS_PORT='6379'

Controls background job processing.

  • QUEUE_DRIVER – database or redis
  • MAX_ATTEMPTS – Retry count for failed jobs
  • REDIS_HOST / REDIS_PORT – Redis connection (if enabled)


⚡ Vite / Frontend Environment

VITE_APP_DOMAIN=${APP_DOMAIN}
VITE_S3_BUCKET=${S3_BUCKET}
VITE_PW_LOWER_CHAR=${PW_LOWER_CHAR}
...

Exposes selected backend values to Vite for frontend builds.

Includes:

  • domain
  • password rules
  • security constraints

This ensures React/UI validation matches backend enforcement.


3. Env Utility Table of Contents

The Env utility helps load and manage environment variables from a .env file.

A. 📌 Features

  • ✅ Loads environment variables from a .env file.
  • ✅ Automatically converts “true” / “false” to booleans.
  • ✅ Automatically converts numeric values to integers or floats.
  • ✅ Provides a get() method to retrieve variables with default values.


B. 🔧 Installation & Setup

The Env utility is automatically included in your framework. To ensure .env is loaded, call:

use Core\Lib\Utilities\Env;

Env::load(ROOT . '/.env');

An example .env file:

APP_NAME="My Custom App"
DEBUG=true
MAX_USERS=100
ENABLE_FEATURE=false


C. 📌 Usage

🔍 Getting an Environment Variable

echo Env::get('APP_NAME'); // Outputs: "My Custom App"

🛠 Providing a Default Value

echo Env::get('NON_EXISTENT_KEY', 'Default Value');

You can also use the globally available version:

echo env(''APP_NAME')

✅ Example Output

.env Value Env::get('KEY') Output
DEBUG=true true (boolean)
MAX_USERS=100 100 (integer)
ENABLE_FEATURE=false false (boolean)
PI=3.14 3.14 (float)


D. 🛠 Debugging

If Env::get('SOME_KEY') returns null, check:

  • The .env file exists at the correct location.
  • The .env file follows the format KEY=VALUE.
  • Restart the server (sudo systemctl restart apache2) or (sudo systemctl restart nginx). If using php console serve press ctrl+c and restart PHP server.


4. Config Utility Table of Contents

The Config utility helps manage configuration files stored in the config/ directory.

A. 📌 Features

  • ✅ Loads configuration files dynamically.
  • ✅ Uses dot notation (config('app.name')) for nested values.
  • ✅ Provides default values when keys are missing.


B. 🔧 Installation & Setup

The Config utility is automatically included in your framework. To load all config files, call:

use Core\Lib\Utilities\Config;

Config::load(ROOT . '/config');

📂 Example config/app.php File

return [
    'name' => Env::get('APP_NAME', 'DefaultApp'),
    'debug' => Env::get('DEBUG', false),
    'timezone' => Env::get('TIME_ZONE', 'UTC'),
];


C. 📌 Usage

🔍 Getting a Config Value

echo Config::get('app.name'); // Outputs: "My Custom App"

🛠 Providing a Default Value

echo Config::get('database.host', '127.0.0.1');

You can also use the globally available version of this function:

echo config('database.host', '127.0.0.1');

📌 Example Config Files config/app.php

return [
    'name' => Env::get('APP_NAME', 'My App'),
    'debug' => Env::get('DEBUG', false),
];

config/database.php

return [
    'host' => Env::get('DB_HOST', '127.0.0.1'),
    'port' => Env::get('DB_PORT', 3306),
    'username' => Env::get('DB_USER', 'root'),
    'password' => Env::get('DB_PASSWORD', ''),
];


D. 📌 Advanced Usage

🔍 Storing Dynamic Configuration

Config::set('app.debug', true);
echo Config::get('app.debug'); // Outputs: true


5. 🚀 Best Practices Table of Contents

  • ✔️ Use .env for sensitive credentials (API keys, database passwords).
  • ✔️ Use Config::get() instead of hardcoding values.
  • ✔️ Ensure all config/*.php files return arrays.


6. 🛠 Debugging Table of Contents

If Config::get('app.name') returns null, check:

  • Config::load(ROOT . '/config'); was called before using Config::get().
  • The file exists in config/ and returns an array.
  • Restart the server if needed.


7. 🎯 Conclusion Table of Contents

  • Env Utility loads environment variables dynamically.
  • Config Utility centralizes configuration management.
  • Use Env::get() for .env values and Config::get() for app settings.