Advanced configuration manager for PHP: a single configuration tree with dotted-path access, case-insensitive keys, and loaders for arrays, PHP files, whole directories and class/object properties — usable either as an injectable object or through a static facade.
- PHP 8.1 or higher
- initphp/parameterbag
^2.0
composer require initphp/config- Dotted paths —
db.hostaddresseshostinside thedbarray. Keys can be nested arbitrarily deep. - Case-insensitive keys —
DB.Host,db.hostandDb.HOSTall refer to the same entry. Keys are folded to lower-case internally. - Three entry points that all share the same read/write contract
(
ConfigInterface):
Declare your configuration as public properties and read it through the shared API:
use InitPHP\Config\Classes;
final class MyAppConfig extends Classes
{
public string $url = 'http://lvh.me';
public string $name = 'LocalHost';
/** @var array<string, string> */
public array $db = [
'host' => 'localhost',
'user' => 'root',
];
}
$config = new MyAppConfig();
$config->get('url'); // "http://lvh.me"
$config->get('db.host'); // "localhost"
$config->get('details', 'Not Found'); // "Not Found"
if ($config->has('name')) {
$config->get('name'); // "LocalHost"
}use InitPHP\Config\Library;
$config = new Library();
$config->set('site.url', 'http://lvh.me')
->set('site.db.host', 'localhost');
$config->get('site.url'); // "http://lvh.me"
$config->get('SITE.DB.HOST'); // "localhost" (case-insensitive)Every call is forwarded to a lazily created, process-wide Library
singleton:
use InitPHP\Config\Config;
Config::setArray('site', ['url' => 'http://lvh.me']);
Config::get('site.url'); // "http://lvh.me"
Config::has('site.url'); // true
Config::reset(); // discard the shared instance (useful in tests)The following methods are available on Classes, Library, and the
Config facade alike:
| Method | Description |
|---|---|
get(string $key, mixed $default = null): mixed |
Read a value, or $default when the key is absent. |
set(string $key, mixed $value): self |
Write a value (intermediate arrays are created as needed). |
has(string $key): bool |
Whether the key exists (a stored null still counts as present). |
remove(string $key): self |
Remove a key (a no-op when it is absent). |
all(): array |
The entire configuration tree as a plain array. |
public function setArray(?string $name, array $assoc = []): self;Imports an associative array. When $name is null or '' the array is
merged into the root; otherwise it is stored under $name.
Config::setArray('site', [
'url' => 'http://lvh.me',
'db' => ['host' => 'localhost', 'user' => 'db_user'],
]);
Config::get('site.url'); // "http://lvh.me"
Config::get('site.db.host'); // "localhost"public function setFile(?string $name, string $path): self;Loads a PHP file that returns an associative array.
// config/db.php
return [
'HOST' => 'localhost',
'USER' => 'root',
];Config::setFile('db', __DIR__ . '/config/db.php');
Config::get('db.host'); // "localhost" (keys are case-insensitive)public function setDir(?string $name, string $path, array $exclude = []): self;Loads every top-level *.php file in a directory. Each file is stored
under a key derived from its base name; when $name is given it becomes a
common prefix. Files can be skipped via $exclude (with or without the
.php suffix).
// config/db.php -> returns ['HOST' => 'localhost']
// config/site.php -> returns ['URL' => 'http://lvh.me']
Config::setDir('app', __DIR__ . '/config', ['secrets']);
Config::get('app.db.host'); // "localhost"
Config::get('app.site.url'); // "http://lvh.me"public function setClass(string|object $classOrObject): self;Imports the public properties of a class or object under the class's short name. A class name imports the property defaults; an instance imports the current values.
namespace App\Config;
class AppConfig
{
public string $url = 'http://lvh.me';
}
class Database
{
public string $host = 'localhost';
}Config::setClass(\App\Config\AppConfig::class); // by class name
Config::setClass(new \App\Config\Database()); // by instance
Config::get('appconfig.url'); // "http://lvh.me"
Config::get('database.host'); // "localhost"A Library exposes top-level entries as read-only nested objects:
$config = new Library();
$config->set('db.host', 'localhost')->set('db.user', 'root');
$config->db->host; // "localhost"
$config->db->user; // "root"Loader failures throw
InitPHP\Config\Exceptions\ConfigException
(a RuntimeException): missing files, files that do not return an array,
invalid directories, and unknown class names.
use InitPHP\Config\Exceptions\ConfigException;
try {
Config::setFile('db', '/path/to/missing.php');
} catch (ConfigException $e) {
// "Configuration file "/path/to/missing.php" was not found."
}In-depth guides with runnable examples live in docs/.
composer test # PHPUnit
composer analyse # PHPStan (level 8)
composer cs:check # PHP-CS-Fixer (dry-run)Released under the MIT License. Copyright © InitPHP.