PHPackages waffle-commons/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. [Framework](/categories/framework) 4. / 5. waffle-commons/config ActiveLibrary[Framework](/categories/framework) waffle-commons/config ===================== Config component for Waffle framework. 0.1.0-beta4(3w ago)1331MITPHPPHP ^8.5CI passing Since Dec 16Pushed 2w agoCompare [ Source](https://github.com/waffle-commons/config)[ Packagist](https://packagist.org/packages/waffle-commons/config)[ RSS](/packages/waffle-commons-config/feed)WikiDiscussions main Synced today READMEChangelog (9)Dependencies (35)Versions (26)Used By (1) [![Discord](https://camo.githubusercontent.com/b30f41baece56d71f7f496f7e39fd33a2a096221c66c648b350dd4fe14276c2e/68747470733a2f2f696d672e736869656c64732e696f2f646973636f72642f3735353238383030313539323033333339313f6c6f676f3d646973636f7264)](https://discord.gg/eKgywnfXr2)[![PHP Version Require](https://camo.githubusercontent.com/c1772585212ac845514159ec9166ca75b59952b95164b03723b64b1a518e10f1/687474703a2f2f706f7365722e707567782e6f72672f776166666c652d636f6d6d6f6e732f636f6e6669672f726571756972652f706870)](https://packagist.org/packages/waffle-commons/config)[![PHP CI](https://github.com/waffle-commons/config/actions/workflows/main.yml/badge.svg)](https://github.com/waffle-commons/config/actions/workflows/main.yml)[![codecov](https://camo.githubusercontent.com/9414400cac48e19720dd3c6907b736d1bcc1b4b0987df119757b555379b63393/68747470733a2f2f636f6465636f762e696f2f67682f776166666c652d636f6d6d6f6e732f636f6e6669672f67726170682f62616467652e7376673f746f6b656e3d64373461633632612d373837322d343033352d386238622d626363336166313939316530)](https://codecov.io/gh/waffle-commons/config)[![Latest Stable Version](https://camo.githubusercontent.com/9812234abd2bdbcb4698952fe9a9751878ec96d1a023106c2de61a42dc2a09b8/687474703a2f2f706f7365722e707567782e6f72672f776166666c652d636f6d6d6f6e732f636f6e6669672f76)](https://packagist.org/packages/waffle-commons/config)[![Latest Unstable Version](https://camo.githubusercontent.com/4d1880dd0ed0448c768a0990db9723a776ae0ae618a3c05366817da51e3213dd/687474703a2f2f706f7365722e707567782e6f72672f776166666c652d636f6d6d6f6e732f636f6e6669672f762f756e737461626c65)](https://packagist.org/packages/waffle-commons/config)[![Total Downloads](https://camo.githubusercontent.com/a7c5b78ec6868c602d29ab57c9371f79416b672dbba2befd79b6085196d1a177/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f776166666c652d636f6d6d6f6e732f636f6e6669672e737667)](https://packagist.org/packages/waffle-commons/config)[![Packagist License](https://camo.githubusercontent.com/6818d6d869aed1c34003158505e83948b134d0a10bdea43491e354f249808b64/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f776166666c652d636f6d6d6f6e732f636f6e666967)](https://github.com/waffle-commons/config/blob/main/LICENSE.md) Waffle Config Component ======================= [](#waffle-config-component) > **Release:** `0.1.0-beta4` | [`CHANGELOG.md`](./CHANGELOG.md) | *Beta-1 hardening retained: no process-env mutation***PHP extension required:** `ext-yaml` (the native PECL YAML extension โ€” *not* Symfony/yaml userland) A strict, typed-getter configuration loader. Reads YAML via the native `ext-yaml` extension with `yaml.decode_php = 0`, eliminating the PHP-deserialisation gadget surface that comes with userland parsers. Environment-specific overlays are applied via `array_replace_recursive`, and `%env(VAR)%` placeholders are resolved at load time **against a read-only env registry injected through the constructor** โ€” never against `getenv()` or `$_ENV` directly (Beta 1 hardening for FrankenPHP worker-mode safety). ๐Ÿ“ฆ Installation -------------- [](#-installation) ``` composer require waffle-commons/config ``` `ext-yaml` must be available in the PHP runtime. The `waffle-dev` Docker image ships with it pre-installed. ๐Ÿงฑ Surface --------- [](#-surface) ClassRole`Waffle\Commons\Config\Config``final` implementation of `ConfigInterface`. Typed getters: `getInt`, `getString`, `getArray`, `getBool`. Accepts a constructor `array $env = []` registry consulted for `%env(VAR)%` resolution.`Waffle\Commons\Config\YamlParser``final` parser wrapper around `yaml_parse_file()` with safe defaults.`Waffle\Commons\Config\DotEnv`**Beta 1**: pure `.env` / `.env.local` parser. `load(): array` returns the parsed map; no longer mutates `putenv()`, `$_ENV`, or `$_SERVER`.`Waffle\Commons\Config\Trait\ParserTrait`Shared parse helpers.`Waffle\Commons\Config\Exception\InvalidConfigurationException`Thrown when a key resolves to a value of the wrong type.๐Ÿš€ Usage ------- [](#-usage) ``` use Waffle\Commons\Config\Config; use Waffle\Commons\Config\DotEnv; use Waffle\Commons\Contracts\Enum\Failsafe; // Build the env registry from .env + process env (rightmost wins โ†’ OS beats .env). $envRegistry = array_merge( (new DotEnv(__DIR__))->load(), getenv() ?: [], ); $config = new Config( configDir: __DIR__ . '/config', environment: 'prod', failsafe: Failsafe::DISABLED, env: $envRegistry, ); $port = $config->getInt('http.port', default: 8080); $debug = $config->getBool('app.debug', default: false); $logs = $config->getArray('logging.channels', default: []); $appName = $config->getString('app.name'); ``` The constructor signature, verbatim from `src/Config.php`: ``` /** * @param array $env Read-only env registry consulted when * resolving `%env(VAR)%` placeholders. Defaults to an empty map. */ public function __construct( string $configDir, string $environment, Failsafe $failsafe = Failsafe::DISABLED, array $env = [], ) ``` ๐Ÿ“ File layout ------------- [](#-file-layout) ``` config/ โ”œโ”€โ”€ app.yaml # base, always loaded โ”œโ”€โ”€ app_dev.yaml # environment overlay (applied if env = "dev") โ”œโ”€โ”€ app_prod.yaml # environment overlay โ””โ”€โ”€ app_test.yaml # environment overlay ``` The base file is loaded first. Then `app_{environment}.yaml` is loaded if it exists, and merged on top of the base via `array_replace_recursive`. `%env(VAR_NAME)%` placeholders anywhere in the resolved tree are expanded against the constructor-injected `$env` registry (see [Environment registry](#-environment-registry-beta-1) below). ๐ŸŒฑ Environment registry (Beta 1) ------------------------------- [](#-environment-registry-beta-1) Beta 1 removes all process-env mutation from this component. The contract is now: 1. **`DotEnv::load(): array`** โ€” pure file parser. Reads `.env` and `.env.local` (first file wins on conflict) and returns the parsed map. Boolean-typed keys (`APP_DEBUG`, `DEBUG`) are validated + normalized to `'1'`/`'0'`; anything else for those keys throws `InvalidArgumentException`. No globals are mutated. 2. **`Config(..., array $env = [])`** โ€” the caller builds the env registry and injects it. `%env(VAR)%` resolution reads from `$this->env[$name] ?? null` โ€” never from `getenv()`, `$_ENV`, or `$_SERVER`. ### Canonical wiring [](#canonical-wiring) ``` $envRegistry = array_merge( (new DotEnv($root))->load(), // left: .env / .env.local getenv() ?: [], // right: OS / Docker / K8s ); ``` `array_merge` is **rightmost-wins** on string keys, so the **process environment beats `.env`** on collision. This matches the Twelve-Factor convention and the implicit precedence of the legacy DotEnv (which silently skipped any key already in `$_ENV` / `$_SERVER`). Flip the order to make `.env` win. > **Type-normalization asymmetry.** DotEnv normalizes `APP_DEBUG`/`DEBUG` booleans; `getenv()` does not. So `APP_DEBUG=yes` in `.env` becomes `'1'`, but the same value exported by the OS becomes `'yes'` โ€” which then fails `Config::getBool('app.debug')` if the YAML uses `'%env(APP_DEBUG)%'`. Either export canonical `true`/`false` values, or normalize `$processEnv` before merging, or use YAML boolean literals instead of `%env()%` for bool keys. See the [how-to guide](../../documentation/how-to/configuration.md) and the [reference doc](../../documentation/reference/config.md) for the full discussion. ๐Ÿ›Ÿ Failsafe mode --------------- [](#-failsafe-mode) When `Failsafe::ENABLED` is passed, `Config` skips file loading and seeds a minimal default tree (`waffle.security.level = 1`). This is used by the `ErrorHandlerMiddleware` boot path so that even a totally broken config still allows the error renderer to run. ๐Ÿ˜ PHP 8.5 features used ----------------------- [](#-php-85-features-used) - Typed getters with `?int`/`?string`/`?array`/`?bool` return types. - `final class Config` and `final class YamlParser` โ€” no subclassing. - Constructor property promotion. - `Failsafe` is an enum from `Waffle\Commons\Contracts\Enum\Failsafe` โ€” backed-string semantics for safe defaulting. ๐Ÿงญ Architectural boundary (`mago guard`) --------------------------------------- [](#-architectural-boundary-mago-guard) An active dependency **perimeter** is enforced on every CI run by `vendor/bin/mago guard` (bundled into `composer mago`; zero baselines). The rules live in [`mago.toml`](./mago.toml) under `[guard.perimeter]` โ€” a forbidden `use` statement fails the build, not a reviewer. Production code under `Waffle\Commons\Config` may depend **only** on: - `Waffle\Commons\Config\**` โ€” itself - `Waffle\Commons\Contracts\**` โ€” the shared contracts package, the **only** Waffle dependency permitted - `Psr\**` โ€” PSR interfaces - `@global` + `Psl\**` โ€” PHP core (including `ext-yaml`) and the PHP Standard Library Test code under `WaffleTests\Commons\Config` is unrestricted (`@all`). Structural rules are guarded too: interfaces must be named `*Interface`, `Exception\**` classes must end in `*Exception`, and any `Enum\**` namespace may hold only `enum` declarations. Contract-first, component-agnostic by construction: components compose through `waffle-commons/contracts`, never directly through one another. ๐Ÿงช Testing --------- [](#-testing) ``` docker exec -w /waffle-commons/config waffle-dev composer tests ``` ๐Ÿ“„ License --------- [](#-license) MIT โ€” see [LICENSE.md](./LICENSE.md). ### Health Score 44 โ€” FairBetter than 90% of packages Maintenance96 Actively maintained with recent releases Popularity12 Limited adoption so far Community13 Small or concentrated contributor base Maturity49 Maturing project, gaining track record 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 ~22 days Recently: every ~5 days Total 9 Last Release 21d ago PHP version history (2 changes)0.1.0-alpha3PHP ^8.4 0.1.0-alpha4PHP ^8.5 ### Community Maintainers ![](https://www.gravatar.com/avatar/34a7557a3fb23aaf788ca3892b9b7efdf96e753264bafd0599153c9e8a921316?d=identicon)[LesliePetrimaux](/maintainers/LesliePetrimaux) --- Top Contributors [![supa-chayajin](https://avatars.githubusercontent.com/u/695448?v=4)](https://github.com/supa-chayajin "supa-chayajin (66 commits)") ### Code Quality TestsPHPUnit Static AnalysisPsalm Type Coverage Yes ### Embed Badge ![Health badge](/badges/waffle-commons-config/health.svg) ``` [![Health](https://phpackages.com/badges/waffle-commons-config/health.svg)](https://phpackages.com/packages/waffle-commons-config) ``` ### Alternatives [nineinchnick/edatatables Grid widget for the Yii Framework, wrapper for the DataTables jQuery plugin 173.2k](/packages/nineinchnick-edatatables)[link-cloud/fast-hyperf LinkCloud Fast Hyperf 241.2k1](/packages/link-cloud-fast-hyperf) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)