Security & Configuration

Design a Reliable PHP Configuration System

Separate secrets from code and manage environment-specific PHP application settings safely.

Overview

Configuration includes database credentials, mail settings, API tokens, feature flags and environment-specific paths. A reliable configuration system makes required settings explicit, validates them early and keeps secrets out of public files and version control.

Keep secrets outside the document root

A common shared-hosting layout places public files in public_html and private configuration in a sibling directory. The exact path depends on the host, but the principle is universal: HTTP requests must not be able to download configuration files. Also deny access to backup files and environment files at the web server layer.

Load and validate configuration once

Avoid reading environment files independently throughout the application. Load settings during bootstrap, validate required values, then pass configuration to the components that need it.

<?php
declare(strict_types=1);

$dbHost = getenv('DB_HOST');
$dbName = getenv('DB_NAME');
$dbUser = getenv('DB_USER');
$dbPass = getenv('DB_PASS');

foreach (['DB_HOST' => $dbHost, 'DB_NAME' => $dbName,
          'DB_USER' => $dbUser, 'DB_PASS' => $dbPass] as $key => $value) {
    if ($value === false || $value === '') {
        throw new RuntimeException("Missing required configuration: {$key}");
    }
}

Do not print secret values in exceptions or diagnostic pages.

Separate environments

Development can enable detailed errors and use test services. Production should log errors privately, disable public error display and use production credentials. Never rely on a user-controlled request parameter to select the environment.

Operational safeguards

Restrict file permissions, rotate credentials when exposed, keep backups protected and ensure deployment scripts do not overwrite private configuration. Use least-privilege database accounts and separate credentials for staging and production.

Checklist

  • Private configuration is outside the public document root.
  • Required values are validated at startup.
  • Secrets are absent from Git and public error output.
  • Production errors go to protected logs.
  • Credentials have only the permissions the application needs.

Official references

PHP environment variables PHP password and cryptography guidance

Load and validate configuration once

Read environment-specific values at bootstrap, validate required values and expose a typed configuration object or a small immutable array. Fail early when a required database DSN or application secret is missing; do not wait until a visitor submits a form.

<?php
declare(strict_types=1);

function requiredEnv(string $name): string
{
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Missing required environment value: {$name}");
    }
    return $value;
}

$config = [
    'app_env' => getenv('APP_ENV') ?: 'production',
    'db_dsn' => requiredEnv('DB_DSN'),
    'db_user' => requiredEnv('DB_USER'),
    'db_password' => requiredEnv('DB_PASSWORD'),
];

This example deliberately does not print secret values. Keep the source of secrets outside version control and restrict file permissions. If a hosting environment uses a private PHP config file rather than environment variables, apply the same validation and access controls.

Separate settings by environment

Development may enable detailed errors and local mail capture. Production should disable display of errors, use private logs and connect only to production services. Do not copy production credentials into a developer laptop or commit a .env file containing real secrets.

Rotate and audit secrets

Document who can access each credential, where it is used and how to rotate it. When a secret may have leaked, revoke it at the provider and deploy a replacement; deleting it from the latest commit is not enough. Keep encryption keys and application secrets separate from ordinary feature flags.

Operational checklist

  • Required settings are validated during bootstrap.
  • Secrets are outside the public web root and excluded from backups shared broadly.
  • Config files have restrictive filesystem permissions.
  • Error messages identify a missing key without exposing its value.
  • Production and development use separate credentials and services.