Usage

Creating a ConfigRepository

use WPZylos\Framework\Config\ConfigRepository;

// Empty repository
$config = new ConfigRepository();

// With initial values
$config = new ConfigRepository([
    'app' => [
        'name' => 'My Plugin',
        'debug' => true,
        'version' => '1.0.0',
    ],
]);

Dot-notation Access

All access methods support dot-notation for nested values.

Getting Values

$config->get('app.name');                    // 'My Plugin'
$config->get('app.debug');                   // true
$config->get('database.host', 'localhost');   // 'localhost' (default)

Setting Values

$config->set('app.version', '2.0.0');
$config->set('database.host', '127.0.0.1');

Checking Existence

$config->has('app.name');     // true
$config->has('app.missing');  // false

Getting All Values

$all = $config->all(); // Returns the entire configuration array

Typed Accessors

Typed accessors return values cast to the expected type with typed defaults.

string()

$config->string('app.name');              // 'My Plugin'
$config->string('app.name', 'Fallback');  // 'My Plugin'
$config->string('missing', 'default');    // 'default'

// Non-string values are cast to string
$config->string('app.debug');  // '1'

int()

$config->int('database.port');        // 3306
$config->int('database.port', 5432);  // 3306 (existing value)
$config->int('missing', 8080);        // 8080 (default)

float()

$config->float('rate.tax');         // 0.15
$config->float('rate.tax', 0.0);   // 0.15 (existing value)
$config->float('missing', 99.99);  // 99.99 (default)

bool()

Handles boolean values and truthy strings ('true', '1', 'yes', 'on').

$config->bool('app.debug');          // true
$config->bool('app.debug', false);   // true (existing value)
$config->bool('missing');            // false (default)

// String values are interpreted
$config->set('feature.enabled', 'yes');
$config->bool('feature.enabled');    // true

$config->set('feature.enabled', 'off');
$config->bool('feature.enabled');    // false

array()

Returns the value if it is an array, otherwise returns the default.

$config->array('app.providers');         // ['Provider1', 'Provider2']
$config->array('app.providers', []);     // ['Provider1', 'Provider2']
$config->array('missing', ['fallback']); // ['fallback']

// Non-array values return the default
$config->set('app.name', 'string');
$config->array('app.name', []);  // [] (not an array, returns default)

Loading from a Directory

Use loadDirectory() to load all PHP files from a config directory. Each file should return an array. The filename (without .php) becomes the top-level config key.

$config = new ConfigRepository();
$config->loadDirectory(__DIR__ . '/config');

Example directory structure:

config/
+-- app.php        → $config->get('app.*')
+-- database.php   → $config->get('database.*')
+-- mail.php       → $config->get('mail.*')

Example config file (config/app.php):

<?php

return [
    'name' => 'My Plugin',
    'debug' => false,
    'version' => '1.0.0',
];

$config->get('app.name');    // 'My Plugin'
$config->get('app.debug');   // false

Note: If the directory does not exist, loadDirectory() silently returns without error.

Merging Configuration

Use merge() to deep-merge additional values into the repository. Uses array_replace_recursive — existing keys at the same path are overwritten, new keys are added.

$config = new ConfigRepository([
    'app' => [
        'name' => 'My Plugin',
        'debug' => false,
    ],
]);

$config->merge([
    'app' => [
        'debug' => true,
        'version' => '2.0',
    ],
]);

$config->get('app.name');    // 'My Plugin' (preserved)
$config->get('app.debug');   // true (overwritten)
$config->get('app.version'); // '2.0' (added)

Environment Variables

EnvLoader

EnvLoader parses .env files and optionally sets $_ENV and putenv() values.

use WPZylos\Framework\Config\EnvLoader;

// Constructor options
$env = new EnvLoader(
    setEnv: true,      // Set values in $_ENV (default: true)
    setPutenv: false    // Set values via putenv() (default: false)
);

// Load a .env file (instance method)
$loaded = $env->load(__DIR__ . '/.env'); // Returns true if loaded, false if missing

// Access parsed values (instance methods)
$env->get('APP_DEBUG');           // 'true'
$env->get('DB_HOST', 'localhost'); // Value or default
$env->has('APP_DEBUG');           // true
$env->all();                     // All parsed key-value pairs

Static env() Helper

The env() static method checks $_ENV first, then getenv(). It does not require a loaded .env file.

use WPZylos\Framework\Config\EnvLoader;

EnvLoader::env('APP_DEBUG', false);
EnvLoader::env('DB_HOST', 'localhost');

.env File Format

# Comments start with #
APP_NAME="My Plugin"
APP_DEBUG=true
DB_HOST=localhost
DB_PORT=3306

# Quoted values support escape sequences
GREETING="Hello\nWorld"

# Single quotes: no escape processing
RAW_VALUE='no\nescapes'

# Special values
EMPTY_VALUE=null
NULLABLE=(null)

# Inline comments (after a space + #)
SECRET=abc123 # this is a comment

Supported special values: true, false, null, empty (and parenthesized forms).

ConfigServiceProvider

When using the WPZylos framework, the ConfigServiceProvider handles everything automatically:

use WPZylos\Framework\Config\ConfigServiceProvider;

During register(), it:

1. Creates a ConfigRepository singleton
2. Loads .env from the plugin root via EnvLoader
3. Loads config files from the @config path via loadDirectory()
4. Binds a 'config' alias in the container

// After registration, resolve from the container:
$config = $app->make(ConfigRepository::class);
$config = $app->make('config');

$config->get('app.name');