README

Load configuration from JSON, PHP, YAML, and TOML files with environment variable substitution.

Requirements

PHP 8.2+
ext-yaml (optional, required for YAML file support)

Installation

composer require philiprehberger/php-config-loader

Usage

Loading a Single File

use PhilipRehberger\ConfigLoader\ConfigLoader;

// Load a PHP config file
$config = ConfigLoader::load(__DIR__ . '/config/app.php');

// Load a JSON config file
$config = ConfigLoader::load(__DIR__ . '/config/database.json');

// Load a YAML config file (requires ext-yaml)
$config = ConfigLoader::load(__DIR__ . '/config/cache.yaml');

// Load a TOML config file
$config = ConfigLoader::load(__DIR__ . '/config/services.toml');

PHP config file (app.php):

<?php
return [
    'name' => 'MyApp',
    'debug' => true,
    'version' => '1.0.0',
];

JSON config file (database.json):

{
    "host": "localhost",
    "port": 3306,
    "credentials": {
        "user": "admin",
        "pass": "secret"
    }
}

Dot-Notation Access

$config->get('credentials.user');          // 'admin'
$config->get('missing.key', 'default');    // 'default'

Typed Getters

$config->string('name');          // string, default ''
$config->int('port', 3306);       // int, default 0
$config->bool('debug', false);    // bool, default false
$config->float('rate', 1.0);      // float, default 0.0
$config->array('tags', []);       // array, default []

Checking Key Existence

$config->has('credentials.user');  // true
$config->has('nonexistent');       // false

Environment Variable Substitution

Config values containing ${VAR} are resolved from environment variables at load time. Use ${VAR:default} to provide a fallback.

{
    "host": "${DB_HOST:localhost}",
    "api_key": "${API_KEY}"
}

putenv('DB_HOST=production.example.com');
$config = ConfigLoader::load('config.json');

$config->get('host');     // 'production.example.com'
$config->get('api_key');  // '' (env var not set, no default)

Loading a Directory

Load all .php, .json, .yaml, .yml, and .toml files from a directory. Each file's basename (without extension) becomes a top-level key.

// config/
//   app.php      -> keyed as 'app'
//   database.json -> keyed as 'database'

$config = ConfigLoader::loadDirectory(__DIR__ . '/config');

$config->get('app.name');           // from app.php
$config->get('database.host');      // from database.json

Deep Merge

Combine two configurations with deep merging. Values from the second config override the first; nested arrays are merged recursively.

$base = ConfigLoader::load('config/defaults.php');
$local = ConfigLoader::load('config/local.php');

$merged = $base->merge($local);

Flattening Nested Config

Convert nested configuration into a flat associative array with dot-notation keys.

$config = ConfigLoader::load('config/database.php');
// ['database' => ['host' => 'localhost', 'port' => 3306]]

$flat = $config->flatten();
// ['database.host' => 'localhost', 'database.port' => 3306]

// Use a custom separator
$flat = $config->flatten('/');
// ['database/host' => 'localhost', 'database/port' => 3306]

Configuration Validation

Validate config values against a set of rules. Rules are pipe-separated.

$config = ConfigLoader::load('config/database.json');

$violations = $config->validate([
    'host' => 'required|string',
    'port' => 'required|int',
    'debug' => 'bool',
]);

if ($violations !== []) {
    foreach ($violations as $message) {
        echo $message . PHP_EOL;
    }
}

Supported rules: required, string, int, bool, float.

API

Method	Return Type	Description
`ConfigLoader::load(string $path)`	`Config`	Load a single config file (PHP, JSON, YAML, TOML)
`ConfigLoader::loadDirectory(string $dir)`	`Config`	Load all config files from a directory
`Config::get(string $key, mixed $default = null)`	`mixed`	Get value by dot-notation key
`Config::string(string $key, string $default = '')`	`string`	Get string value
`Config::int(string $key, int $default = 0)`	`int`	Get integer value
`Config::bool(string $key, bool $default = false)`	`bool`	Get boolean value
`Config::float(string $key, float $default = 0.0)`	`float`	Get float value
`Config::array(string $key, array $default = [])`	`array`	Get array value
`Config::has(string $key)`	`bool`	Check if key exists
`Config::all()`	`array`	Get all config data
`Config::keys()`	`array`	Get all top-level configuration keys
`Config::merge(Config $other)`	`Config`	Deep merge with another config
`Config::flatten(string $separator = '.')`	`array`	Flatten nested config to dot-notation key-value pairs
`Config::validate(array $rules)`	`array`	Validate config against rules, returns violation messages

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT

philiprehberger / php-config-loader

Maintainers

Package info

Fund package maintenance!

Statistics

Security