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.