PHPackages                             roots/wp-config - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. roots/wp-config

ActiveLibrary[Utility & Helpers](/categories/utility)

roots/wp-config
===============

Fluent configuration management for WordPress

1.0.0(7y ago)587.5M—2.9%720MITPHPPHP >=5.6CI passing

Since Aug 10Pushed 1mo ago8 watchersCompare

[ Source](https://github.com/roots/wp-config)[ Packagist](https://packagist.org/packages/roots/wp-config)[ RSS](/packages/roots-wp-config/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (4)Versions (7)Used By (20)

wp-config
=========

[](#wp-config)

[![Build Status](https://camo.githubusercontent.com/f767cb4313abc85bfc92ab9018f0796300727bd86decd91315ce28468a816817/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f726f6f74732f77702d636f6e6669672f6d61696e2e796d6c3f6272616e63683d6d6173746572266c6f676f3d676974687562266c6162656c3d4349267374796c653d666c61742d737175617265)](https://github.com/roots/wp-config/actions/workflows/main.yml)[![Packagist Downloads](https://camo.githubusercontent.com/b98500482974a1cf949786d5d01607ab727b6dc1395ea7d4dec587478d517a36/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f726f6f74732f77702d636f6e6669673f6c6162656c3d646f776e6c6f61647326636f6c6f72423d32623330373226636f6c6f72413d353235646463267374796c653d666c61742d737175617265)](https://packagist.org/packages/roots/wp-config)[![Follow Roots](https://camo.githubusercontent.com/222256dbdeac58e77f017d847dca30ff4cab027cdf3abfec8e5bfd59de240547/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f666f6c6c6f7725323040726f6f747377702d3164613166323f6c6f676f3d74776974746572266c6f676f436f6c6f723d666666666666266d6573736167653d267374796c653d666c61742d737175617265)](https://twitter.com/rootswp)[![Sponsor Roots](https://camo.githubusercontent.com/31e13361135ff96d01f1eb97157d052029e6f236249996072d8b6bd60b40e9cd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f73706f6e736f72253230726f6f74732d3532356464633f6c6f676f3d676974687562267374796c653d666c61742d737175617265266c6f676f436f6c6f723d666666666666266d6573736167653d)](https://github.com/sponsors/roots)

Fluent configuration management for WordPress

```
$config = Config::make($rootDir)->bootstrapEnv();

$config
    ->env('WP_ENV', 'production')
    ->env('WP_HOME')
    ->set('WP_DEBUG', true)
    ->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 via `vlucas/phpdotenv`
- Conditional configuration with `when()`
- Instance-scoped hook system for extensible configuration

Support us
----------

[](#support-us)

Roots is an independent open source org, supported only by developers like you. Your sponsorship funds [WP Packages](https://wp-packages.org/) and the entire Roots ecosystem, and keeps them independent. Support us by purchasing [Radicle](https://roots.io/radicle/) or [sponsoring us on GitHub](https://github.com/sponsors/roots) — sponsors get access to our private Discord.

Requirements
------------

[](#requirements)

- PHP >= 8.1
- Composer

Installation
------------

[](#installation)

```
composer require roots/wp-config:^2.0
```

Usage
-----

[](#usage)

### Basic configuration

[](#basic-configuration)

```
use Roots\WPConfig\Config;

$config = Config::make($rootDir)->bootstrapEnv();

$config
    ->set('WP_DEBUG', true)
    ->set('WP_HOME', 'https://example.com')
    ->apply();
```

### Conditional configuration

[](#conditional-configuration)

```
$config
    ->env('WP_ENV', 'production')
    ->when($config->get('WP_ENV') === 'development', function($config) {
        $config
            ->set('WP_DEBUG', true)
            ->set('SAVEQUERIES', true)
            ->set('SCRIPT_DEBUG', true);
    });
```

### Accessing values

[](#accessing-values)

```
$home = $config->get('WP_HOME');

// With a default value (no exception if key is missing)
$env = $config->get('WP_ENV', 'production');

$config
    ->set('WP_SITEURL', $config->get('WP_HOME') . '/wp')
    ->apply();
```

### Environment variables

[](#environment-variables)

The Config class includes built-in support for loading environment variables:

```
$config->bootstrapEnv(); // Loads .env and .env.local files

$config
    ->env('DB_NAME')
    ->env('DB_USER')
    ->env('DB_HOST', 'localhost')
    ->apply();
```

### Hook system

[](#hook-system)

The Config class includes an instance-scoped hook system for extensible configuration:

```
// Register a hook
$config->addAction('security_setup', function($config) {
    $config->set('FORCE_SSL_ADMIN', true);
    $config->set('DISALLOW_FILE_EDIT', true);
});

// Execute the hook
$config
    ->set('WP_ENV', 'production')
    ->doAction('security_setup')
    ->apply();
```

#### Automatic `before_apply` hook

[](#automatic-before_apply-hook)

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->addAction('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
    ->env('WP_HOME')
    ->set('WP_SITEURL', $config->get('WP_HOME') . '/wp')
    ->apply(); // Automatically runs all before_apply hooks
```

Upgrading from v1
-----------------

[](#upgrading-from-v1)

### Step 1: Update `composer.json`

[](#step-1-update-composerjson)

```
{
  "require": {
    "roots/wp-config": "^2.0"
  }
}
```

### Step 2: Replace static calls

[](#step-2-replace-static-calls)

Before:

```
Config::define('WP_DEBUG', true);
Config::define('WP_HOME', env('WP_HOME'));
Config::apply();
```

After:

```
$config = Config::make($rootDir);
$config
    ->set('WP_DEBUG', true)
    ->env('WP_HOME')
    ->apply();
```

### Step 3: Consolidate environment files

[](#step-3-consolidate-environment-files)

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
    ->env('WP_ENV', 'production')
    ->env('WP_HOME')
    ->when($config->get('WP_ENV') === 'development', function($config) {
        $config
            ->set('WP_DEBUG', true)
            ->set('SAVEQUERIES', true);
    })
    ->apply();
```

### Step 4: Update environment loading

[](#step-4-update-environment-loading)

Before:

```
$dotenv = Dotenv::createImmutable($rootDir);
$dotenv->load();
```

After:

```
$config = Config::make($rootDir)->bootstrapEnv();
```

### Step 5: Update hook usage

[](#step-5-update-hook-usage)

Hooks are now instance methods instead of static methods:

Before:

```
Config::add_action('before_apply', function($config) { ... });
```

After:

```
$config->addAction('before_apply', function($config) { ... });
```

### Removed APIs

[](#removed-apis)

- `Config::remove()` has been removed. Use `when()` blocks to conditionally set values instead.
- `set()` now overwrites previous values for the same key (useful in `when()` blocks for overriding defaults).

API reference
-------------

[](#api-reference)

### Config class

[](#config-class)

#### `__construct(string $rootDir)`

[](#__constructstring-rootdir)

Creates a new Config instance with the specified root directory.

#### `make(string $rootDir): static`

[](#makestring-rootdir-static)

Creates a new Config instance with a fluent-friendly named constructor.

#### `bootstrapEnv(): self`

[](#bootstrapenv-self)

Loads environment variables from .env files.

#### `set(string|array $key, mixed $value = null): self`

[](#setstringarray-key-mixed-value--null-self)

Sets a configuration value. Accepts a key/value pair or an associative array. Overwrites existing config map entries. Throws `ConstantAlreadyDefinedException` if a PHP constant with that name already exists.

#### `env(string|array $key, mixed $default = null): self`

[](#envstringarray-key-mixed-default--null-self)

Sets a configuration value from an environment variable. Falls back to `$default` if the variable is not set.

#### `get(string $key, mixed $default = null): mixed`

[](#getstring-key-mixed-default--null-mixed)

Gets a configuration value. Returns `$default` if the key is not set and a default is provided. Throws `UndefinedConfigKeyException` if the key is not set and no default is provided.

#### `when(bool|Closure $condition, callable $callback): self`

[](#whenboolclosure-condition-callable-callback-self)

Conditionally executes configuration logic. The condition can be a boolean or a Closure that receives the Config instance.

#### `apply(): void`

[](#apply-void)

Applies all configuration values by defining constants. Automatically runs `before_apply` hooks first.

#### `addAction(string $tag, callable $callback, int $priority = 10): self`

[](#addactionstring-tag-callable-callback-int-priority--10-self)

Adds a hook callback that can be executed later with `doAction()`. Returns `$this` for chaining.

#### `doAction(string $tag, ...$args): self`

[](#doactionstring-tag-args-self)

Executes all callbacks registered for the specified hook. Returns `$this` for chaining.

### Exceptions

[](#exceptions)

- `ConstantAlreadyDefinedException`: Thrown when attempting to redefine a constant
- `UndefinedConfigKeyException`: Thrown when accessing an undefined configuration key without a default

Full example
------------

[](#full-example)

A complete Bedrock-style `application.php` configuration file:

```