PHPackages liquidrazor/config-loader - 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. liquidrazor/config-loader ActiveLibrary[Utility & Helpers](/categories/utility) liquidrazor/config-loader ========================= A lightweight, data-only configuration loading library for PHP 8.3+. v0.1.1(3mo ago)03↓92.3%2MITPHPPHP ^8.3 Since Apr 3Pushed 3mo agoCompare [ Source](https://github.com/LiquidRazor/ConfigLoader)[ Packagist](https://packagist.org/packages/liquidrazor/config-loader)[ RSS](/packages/liquidrazor-config-loader/feed)WikiDiscussions main Synced today READMEChangelogDependencies (1)Versions (3)Used By (2) ConfigLoader ============ [](#configloader) A lightweight, data-only configuration loading library for PHP 8.3+. ConfigLoader provides a deterministic and strict pipeline for loading application configuration from a single declarative format, applying layered overrides and environment interpolation, and returning a final normalized array. No executable configuration. No framework coupling. No hidden magic. Documentation ------------- [](#documentation) - Overview - [Purpose](docs/01_overview/purpose.md) - [Concepts](docs/01_overview/concepts.md) - Architecture - [Structure](docs/02_architecture/structure.md) - [Pipeline](docs/02_architecture/pipeline.md) - [Decisions](docs/02_architecture/decisions.md) - Components - [ConfigLoader](docs/03_components/config-loader.md) - [Parsers](docs/03_components/parsers.md) - [Interpolation](docs/03_components/interpolation.md) - [Merge](docs/03_components/merge.md) - [Exceptions](docs/03_components/exceptions.md) - Usage - [Basic Usage](docs/04_usage/basic-usage.md) - [Layered Config](docs/04_usage/layered-config.md) - [Interpolation](docs/04_usage/interpolation.md) - [Format Selection](docs/04_usage/format-selection.md) - Development - [Contributing](docs/05_development/contributing.md) - [Testing](docs/05_development/testing.md) - [Extension Guidance](docs/05_development/extension.md) --- Philosophy ---------- [](#philosophy) Config is **data**, not code. ConfigLoader enforces: - Single format per project (no YAML + JSON chaos) - Declarative configuration only (no PHP execution) - Deterministic behavior (no surprises, no implicit merging tricks) - Strict failure on invalid syntax or unresolved values This keeps configuration: - predictable - portable - inspectable - safe to evolve --- Features -------- [](#features) - YAML support (default) - JSON support (explicit opt-in) - Config root resolution - Layered configuration merging - Environment variable interpolation - Strict error handling - Array output only --- Non-Goals --------- [](#non-goals) ConfigLoader deliberately does **not** provide: - Schema validation (handled by a separate future library) - Executable config (PHP files are not supported) - Application-specific logic - Framework integration - File system discovery beyond config root --- Installation ------------ [](#installation) ``` composer require liquidrazor/config-loader ``` --- Basic Usage ----------- [](#basic-usage) ``` $loader = new ConfigLoader( new LoaderOptions( configRoot: __DIR__ . '/config' ) ); $config = $loader->load('services'); ``` --- Config Root ----------- [](#config-root) By default, configuration is expected in: ``` /config ``` You can override this: ``` new LoaderOptions( configRoot: '/custom/path/to/config' ); ``` --- Supported Formats ----------------- [](#supported-formats) ### YAML (default) [](#yaml-default) - Preferred format - Uses `ext-yaml` if available - Falls back to internal parser otherwise Supported extensions: ``` .yaml .yml ``` --- ### JSON (explicit) [](#json-explicit) Must be explicitly enabled: ``` new LoaderOptions( configRoot: __DIR__ . '/config', format: ConfigFormat::JSON ); ``` Supported extension: ``` .json ``` JSON requires the PHP `ext-json` extension. If `ext-json` is unavailable, install it or switch the loader format to YAML. --- ### Important [](#important) A loader instance supports **only one format**. Mixing formats is not allowed. --- File Resolution --------------- [](#file-resolution) Config is loaded by logical name: ``` $loader->load('services'); ``` Resolves to: ``` config/services.yaml ``` (or `.json` depending on format) --- Layered Configuration --------------------- [](#layered-configuration) ConfigLoader supports layered overrides. Example: ``` $loader->loadLayered('services', ['prod', 'local']); ``` Resolves and merges in order: ``` services.yaml services.prod.yaml services.local.yaml ``` --- Merge Behavior -------------- [](#merge-behavior) Default merge rules: - Associative arrays → recursive merge - Scalar values → overridden by later layers - Indexed arrays → fully replaced (not appended) This ensures predictable behavior and avoids duplication issues. --- Environment Interpolation ------------------------- [](#environment-interpolation) Environment variables can be interpolated inside config values. ### Syntax [](#syntax) ``` ${VAR_NAME} ${VAR_NAME:-default} ``` ### Example [](#example) ``` database: host: ${DB_HOST:-localhost} port: ${DB_PORT} ``` ### Behavior [](#behavior) - Interpolation is applied **after merging** - Missing variables without defaults throw an exception - Only string values are interpolated - No expression evaluation or casting is performed --- Error Handling -------------- [](#error-handling) ConfigLoader fails fast and loudly: - Invalid syntax → exception - Missing config file → exception - Unsupported format → exception - Missing env variable → exception No silent fallbacks. No guessing. --- Internal Pipeline ----------------- [](#internal-pipeline) The configuration loading process follows a strict pipeline: ``` resolve files → parse → merge → interpolate → return array ``` Each stage is isolated and deterministic. --- Architecture ------------ [](#architecture) Project structure follows: ``` include/ → contracts, enums, value objects, exceptions lib/ → core logic (loader, parsers, interpolation, merge) src/ → optional bootstrap/factory (minimal) ``` ### Core Components [](#core-components) - ConfigLoader - YamlParser - JsonParser - EnvInterpolator - LayeredConfigMerger --- Design Principles ----------------- [](#design-principles) - No hidden behavior - No implicit format mixing - No execution in config - No framework dependencies - Minimal, composable components --- Future Scope ------------ [](#future-scope) Planned but intentionally excluded from this library: - Schema validation (separate library) - DSN parsing - Advanced config composition - Environment profiles abstraction --- Summary ------- [](#summary) ConfigLoader is a strict, minimal, and predictable configuration pipeline. It does one job: **Load configuration as data, correctly.** Nothing more. Nothing less. ### Health Score 35 — LowBetter than 77% of packages Maintenance82 Actively maintained with recent releases Popularity3 Limited adoption so far Community10 Small or concentrated contributor base Maturity40 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 ~0 days Total 2 Last Release 93d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/4306922?v=4)[Noramarth](/maintainers/Noramarth)[@Noramarth](https://github.com/Noramarth) --- Top Contributors [![Noramarth](https://avatars.githubusercontent.com/u/4306922?v=4)](https://github.com/Noramarth "Noramarth (2 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/liquidrazor-config-loader/health.svg) ``` [![Health](https://phpackages.com/badges/liquidrazor-config-loader/health.svg)](https://phpackages.com/packages/liquidrazor-config-loader) ``` ### Alternatives [jijunair/laravel-referral Laravel package for a referral system 9434.5k](/packages/jijunair-laravel-referral)[aerni/cloudflared A Laravel package to create and manage Cloudflare Tunnels for local development 879.5k](/packages/aerni-cloudflared) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)