Fluent configuration management for WordPress
$config = new Config($rootDir);
$config
->set('WP_DEBUG', true)
->set('WP_HOME', env('WP_HOME'))
->when($config->get('WP_ENV') === 'development', function($config) {
$config
->set('SAVEQUERIES', true)
->set('SCRIPT_DEBUG', true);
})
->apply();- 🔄 Fluent API for clean, chainable configuration
- 🌍 Built-in environment variable loading
- 🔀 Conditional configuration with
when() - 🪝 WordPress-style hook system for extensible configuration
- 📦 Zero dependencies (except
vlucas/phpdotenv)
- PHP >= 8.1
- Composer
composer require roots/wp-config:^2.0use Roots\WPConfig\Config;
$config = new Config($rootDir);
$config->bootstrapEnv();
$config
->set('WP_DEBUG', true)
->set('WP_HOME', 'https://example.com')
->apply();$config
->when(env('WP_ENV') === 'development', function($config) {
$config
->set('WP_DEBUG', true)
->set('SAVEQUERIES', true)
->set('SCRIPT_DEBUG', true);
});$home = $config->get('WP_HOME');
$config
->set('WP_SITEURL', $config->get('WP_HOME') . '/wp')
->apply();The Config class includes built-in support for loading environment variables:
$config->bootstrapEnv(); // Loads .env and .env.local files
$config
->set('DB_NAME', env('DB_NAME'))
->set('DB_USER', env('DB_USER'))
->apply();The Config class includes a WordPress-style hook system for extensible configuration:
// Register a hook
Config::add_action('security_setup', function($config) {
$config->set('FORCE_SSL_ADMIN', true);
$config->set('DISALLOW_FILE_EDIT', true);
});
// Execute the hook
$config
->set('WP_ENV', 'production')
->do_action('security_setup')
->apply();The Config class automatically executes any before_apply hooks when apply() is called. This enables packages to register configuration logic that runs automatically without requiring manual hook calls:
// Package authors can register automatic configuration
Config::add_action('before_apply', function($config) {
// This runs automatically when apply() is called
$config->set('AUTOMATIC_CONFIG', 'set by package');
});
// Users just need to call apply() - no manual hook management required
$config
->set('WP_HOME', env('WP_HOME'))
->set('WP_SITEURL', env('WP_HOME') . '/wp')
->apply(); // Automatically runs all before_apply hooksThis pattern is especially useful for packages that need to configure WordPress automatically without requiring users to manually call hooks in their configuration files.
{
"require": {
"roots/wp-config": "^2.0"
}
}Before:
Config::define('WP_DEBUG', true);
Config::define('WP_HOME', env('WP_HOME'));
Config::apply();After:
$config = new Config($rootDir);
$config
->set('WP_DEBUG', true)
->set('WP_HOME', env('WP_HOME'))
->apply();Before:
// config/environments/development.php
Config::define('WP_DEBUG', true);
Config::define('SAVEQUERIES', true);
// config/application.php
Config::define('WP_HOME', env('WP_HOME'));
Config::apply();After:
$config
->set('WP_HOME', env('WP_HOME'))
->when($config->get('WP_ENV') === 'development', function($config) {
$config
->set('WP_DEBUG', true)
->set('SAVEQUERIES', true);
})
->apply();Before:
$dotenv = Dotenv::createImmutable($rootDir);
$dotenv->load();After:
$config = new Config($rootDir);
$config->bootstrapEnv();Creates a new Config instance with the specified root directory.
Loads environment variables from .env files.
Sets a configuration value.
Gets a configuration value.
Conditionally executes configuration logic.
Applies all configuration values by defining constants.
Adds a hook callback that can be executed later with do_action(). Static method.
Executes all callbacks registered for the specified hook. Returns $this for chaining.
ConstantAlreadyDefinedException: Thrown when attempting to redefine a constantUndefinedConfigKeyException: Thrown when accessing an undefined configuration key