PHPackages                             initphp/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. initphp/config

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

initphp/config
==============

Advanced configuration manager for PHP with dotted-path access, file/directory/class loaders and a static facade.

2.0.0(1mo ago)21291MITPHPPHP ^8.1CI passing

Since Mar 16Pushed 3w ago1 watchersCompare

[ Source](https://github.com/InitPHP/Config)[ Packagist](https://packagist.org/packages/initphp/config)[ RSS](/packages/initphp-config/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (5)Versions (5)Used By (1)

InitPHP Config
==============

[](#initphp-config)

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.

[![CI](https://github.com/InitPHP/Config/actions/workflows/ci.yml/badge.svg)](https://github.com/InitPHP/Config/actions/workflows/ci.yml)[![Latest Stable Version](https://camo.githubusercontent.com/ee4b71e368dc8d37a42bc28ffa8a46027a40ffe3be2d3feeb72cf5d809a6c0a3/687474703a2f2f706f7365722e707567782e6f72672f696e69747068702f636f6e6669672f76)](https://packagist.org/packages/initphp/config)[![Total Downloads](https://camo.githubusercontent.com/852d4739fb4c6bd981725db72bf48113f5f8aa5854bbfc8b2cfaa2e2e2b40ddb/687474703a2f2f706f7365722e707567782e6f72672f696e69747068702f636f6e6669672f646f776e6c6f616473)](https://packagist.org/packages/initphp/config)[![License](https://camo.githubusercontent.com/3b2bac7ef05e303f770207b6a761552601984f6b6309e65a7944fd8e20d15816/687474703a2f2f706f7365722e707567782e6f72672f696e69747068702f636f6e6669672f6c6963656e7365)](https://packagist.org/packages/initphp/config)[![PHP Version Require](https://camo.githubusercontent.com/79deebeb825ed4cea031ab3c598afcfbaaa61555e8fca618822c15fd6f089c91/687474703a2f2f706f7365722e707567782e6f72672f696e69747068702f636f6e6669672f726571756972652f706870)](https://packagist.org/packages/initphp/config)

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

[](#requirements)

- PHP 8.1 or higher
- [initphp/parameterbag](https://github.com/InitPHP/ParameterBag) `^2.0`

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

[](#installation)

```
composer require initphp/config
```

Key Concepts
------------

[](#key-concepts)

- **Dotted paths** — `db.host` addresses `host` inside the `db` array. Keys can be nested arbitrarily deep.
- **Case-insensitive keys** — `DB.Host`, `db.host` and `Db.HOST` all refer to the same entry. Keys are folded to lower-case internally.
- **Three entry points** that all share the same read/write contract ([`ConfigInterface`](src/Interfaces/ConfigInterface.php)):
    - [`Classes`](src/Classes.php) — turn a class's public properties into configuration.
    - [`Library`](src/Library.php) — an injectable object with the full loader API.
    - [`Config`](src/Config.php) — a static facade over a shared `Library`.

Quick Start
-----------

[](#quick-start)

### Configuration classes

[](#configuration-classes)

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 */
    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"
}
```

### The `Library` object

[](#the-library-object)

```
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)
```

### The `Config` static facade

[](#the-config-static-facade)

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)
```

Reading and writing
-------------------

[](#reading-and-writing)

The following methods are available on `Classes`, `Library`, and the `Config` facade alike:

MethodDescription`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.Loaders (`Library` / `Config`)
------------------------------

[](#loaders-library--config)

### `setArray()`

[](#setarray)

```
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"
```

### `setFile()`

[](#setfile)

```
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)
```

### `setDir()`

[](#setdir)

```
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"
```

### `setClass()`

[](#setclass)

```
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"
```

Object-style access (`Library`)
-------------------------------

[](#object-style-access-library)

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"
```

Error handling
--------------

[](#error-handling)

Loader failures throw [`InitPHP\Config\Exceptions\ConfigException`](src/Exceptions/ConfigException.php)(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."
}
```

Documentation
-------------

[](#documentation)

In-depth guides with runnable examples live in [`docs/`](docs/README.md).

Testing
-------

[](#testing)

```
composer test      # PHPUnit
composer analyse   # PHPStan (level 8)
composer cs:check  # PHP-CS-Fixer (dry-run)
```

Credits
-------

[](#credits)

- [Muhammet ŞAFAK](https://www.muhammetsafak.com.tr) —

License
-------

[](#license)

Released under the [MIT License](LICENSE). Copyright © InitPHP.

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance94

Actively maintained with recent releases

Popularity13

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~516 days

Total

4

Last Release

23d ago

Major Versions

1.x-dev → 2.0.02026-05-29

PHP version history (2 changes)1.0PHP >=7.4

2.0.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/4b6b34f3ac8938d8ee52ba3bd260680855dc5715c7b2929d9380de30d15a67dd?d=identicon)[muhammetsafak](/maintainers/muhammetsafak)

---

Top Contributors

[![muhammetsafak](https://avatars.githubusercontent.com/u/104234499?v=4)](https://github.com/muhammetsafak "muhammetsafak (3 commits)")

---

Tags

configconfig-managerconfigurationconfiguration-managementdot-notationdotted-pathinitphpparameter-bagphpphp-configphp-configurationphp-librarysettingsphpconfigurationSettingsconfigPHP Librarydot notationinitphpconfig managerparameter-bagdotted-path

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/initphp-config/health.svg)

```
[![Health](https://phpackages.com/badges/initphp-config/health.svg)](https://phpackages.com/packages/initphp-config)
```

###  Alternatives

[jbtronics/settings-bundle

A symfony bundle to easily create typesafe, user-configurable settings for symfony applications

9773.0k3](/packages/jbtronics-settings-bundle)[selective/config

Config component, strictly typed

19194.8k3](/packages/selective-config)[michaels/data-manager

Simple data manager for nested data, dot notation array access, extendability, and container interoperability.

132.0k2](/packages/michaels-data-manager)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)