🔧 Configuration & Settings

This guide explains where configuration lives, how precedence works, and practical examples for database, site, email, security, logging, and theming.

TL;DR: Most installs configure includes/config.php (required) and optionally override with environment variables for secrets.

1) Where Configuration Lives

Load order recommendation: config.php → site-config.php → environment overrides → module settings (runtime).

2) Quick Start Checklist

3) Minimal includes/config.php Example

<?php
// === Database ===
define('DB_HOST', getenv('DB_HOST') ?: 'localhost');
define('DB_NAME', getenv('DB_NAME') ?: 'phpstrap');
define('DB_USER', getenv('DB_USER') ?: 'phpstrap_user');
define('DB_PASS', getenv('DB_PASS') ?: 'change-me');
define('DB_CHARSET', 'utf8mb4');

// === App ===
define('APP_ENV', getenv('APP_ENV') ?: 'production'); // 'local'|'staging'|'production'
define('APP_DEBUG', (bool) (getenv('APP_DEBUG') ?: false));
date_default_timezone_set(getenv('APP_TZ') ?: 'UTC');

// === URLs & Paths ===
$https = (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off');
$scheme = $https ? 'https' : 'http';
$host   = $_SERVER['HTTP_HOST'] ?? 'localhost';
define('BASE_URL', getenv('BASE_URL') ?: "{$scheme}://{$host}/");

// === Sessions & Cookies ===
ini_set('session.cookie_httponly', '1');
ini_set('session.use_only_cookies', '1');
if ($https) { ini_set('session.cookie_secure', '1'); }

// === Logging ===
define('LOG_DIR', __DIR__ . '/../logs'); // ensure writable
if (!is_dir(LOG_DIR)) { @mkdir(LOG_DIR, 0755, true); }

// === Feature Flags ===
define('FEATURE_DARK_MODE_DEFAULT', true);
define('FEATURE_RATE_LIMIT', true);

// === Security ===
define('ADMIN_PATH', getenv('ADMIN_PATH') ?: '/admin/'); // you can customize
// Example CORS/headers can be added in bootstrap as needed

// === Mail (fallbacks; prefer SMTP Module for secrets) ===
define('MAIL_FROM_EMAIL', getenv('MAIL_FROM_EMAIL') ?: 'no-reply@example.com');
define('MAIL_FROM_NAME', getenv('MAIL_FROM_NAME') ?: 'PhPstrap');

// === Captcha provider hint (module-driven) ===
define('CAPTCHA_PROVIDER', getenv('CAPTCHA_PROVIDER') ?: 'hcapture'); // or 'none'

// === Include an optional site-config if present ===
$siteCfg = __DIR__ . '/site-config.php';
if (file_exists($siteCfg)) { require_once $siteCfg; }

4) Optional includes/site-config.php (Branding/Theme)

<?php
// Branding
if (!defined('SITENAME')) define('SITENAME', 'Your Site Name');
if (!defined('SITEURL'))  define('SITEURL', rtrim(BASE_URL, '/'));

// Appearance
if (!defined('THEME_COLOR')) define('THEME_COLOR', '#0d6efd');
define('DEFAULT_THEME', 'auto'); // 'light'|'dark'|'auto'

5) Environment Variables (Recommended for Secrets)

Set env vars at the web server, container, or OS level. Example shell export:

# Linux shell example
export APP_ENV=production
export DB_HOST=localhost
export DB_NAME=phpstrap
export DB_USER=phpstrap_user
export DB_PASS='supersecret'
export MAIL_FROM_EMAIL='no-reply@yourdomain.com'
export ADMIN_PATH='/secure-admin/'

If you use a custom loader (e.g., vlucas/phpdotenv), add a .env file outside web root and never commit it.

6) Database Settings

7) Email Transport

Best practice: Install the SMTP module and configure it in Admin → Modules → SMTP → Settings.

If you need a quick fallback without the module, wire a simple PHP mailer that reads the constants above — but prefer the module for maintainability and secret isolation.

8) Security Options

9) Sessions & Cookies

10) Logging

# Example logrotate snippet (Linux)
/var/www/yourapp/logs/*.log {
  weekly
  rotate 8
  compress
  missingok
  notifempty
  create 0640 www-data www-data
}

11) Uploads & Static Assets

# .htaccess example to disable PHP execution in uploads
<FilesMatch "\.php$">
  Deny from all
</FilesMatch>

12) URL & Routing Tips

13) Theming & Appearance

14) Feature Flags

Gate experimental features behind constants or env flags and read them in controllers/views.

<?php if (defined('FEATURE_RATE_LIMIT') && FEATURE_RATE_LIMIT) {
  // apply rate limiting middleware
}

15) Troubleshooting

For production hardening, also review the Admin Panel Security Checklist. Need help? Open an issue: GitHub Issues.