Config Laravel Package

Product Decisions This Supports

• Build vs. buy on a config engine. The core decision this package informs: do we hand-roll schema definition, deep merge, normalization, defaults and error reporting for a config-driven feature, or adopt a mature node-tree implementation? The changelog is the strongest evidence here — repeated fixes across 2024–2026 for deep-merge of required keys, alternative types on nested prototyped arrays, enum normalization in array shapes and env placeholders in numeric bounds (#63478, #64042, #64106, #64045) show this is a deceptively subtle problem space. That argues for consuming rather than owning the merge/validation semantics.
• Whether to ship a "semantic configuration" contract for our own packages or third-party extensions. If the roadmap includes a plugin/extension ecosystem, or enterprise customers shipping YAML/XML config, this component gives a typed schema as the public contract: definitions, defaults autofill, and validation errors that carry config paths — far better DX than array-key guessing.
• Roadmap bet on schema-first tooling. The 7.4/8.0 line invests in ArrayShapeGenerator and auto-generated config/reference.php, plus deprecating the fluent PHP builder in favor of PHP array config that mirrors YAML shape. If we adopt, standardizing on the array-based config format aligns us with where upstream is spending effort and avoids a migration we'd otherwise pay for twice.
• Multi-format ingress as a feature, not a chore. "Any source — YAML, XML, INI, database" is a real product lever for self-hosted/on-prem and regulated buyers who expect file-based config with XSD-validated structure, without us writing three parsers.
• Concrete use cases worth scoring: (a) extension/plugin configuration with autofill + validation; (b) per-tenant or per-customer config loaded from DB with resource-tracking-driven cache invalidation; (c) generated config reference docs and static-analysis types for a config schema we publish; (d) migration tooling where config file formats evolve and we need normalization between generations.
• An explicit non-decision to record: this is not a runtime settings store. Symfony Config is largely load/compile-time. If the requirement is an admin-editable, hot-reloadable settings surface, don't let this package's presence in the backlog imply it solves that.
• Dependency-surface decision for a Laravel codebase. Laravel's own Illuminate\Config\Repository (dot-notation arrays, env(), config caching) already covers flat app config. Adding symfony/config is a new configuration paradigm alongside the existing one, so the decision is really "two config systems, clearly scoped" vs. "one, with weaker schema guarantees."

When to Consider This Package

Adopt when most of these hold:

• The config surface is nested and non-trivial — multiple node types, lists of sub-configs, mutually exclusive options, per-node defaults, and you want defaults applied automatically rather than scattered through call sites.
• Config arrives from more than one source or format, or from third parties whose files you don't control.
• You need precise, path-addressable validation errors surfaced to users (a support-cost and NPS lever, not just a code-quality one).
• You need cache invalidation tied to config resources — file/glob/class-reflection tracking so a changed YAML or class doesn't silently serve stale compiled config.
• You want generated types/reference docs for a config schema you expose publicly.
• You're willing to accept the integration cost: this is a Symfony component, not a Laravel package. There is no .env/env() bridge, no config-repository bridge, and no Laravel-documented path. We own the glue and the docs.

Look elsewhere (or defer) when:

• Config is flat key/value and env-driven — config() plus a typed DTO and Laravel's validator is cheaper than standing up a node tree.
• You need a mutable runtime settings store with UI, per-request overrides or hot reload. This is a schema/load-time tool; forcing it into that role will fight it.
• PHP floor is the blocker. Symfony 8 requires PHP ≥ 8.4. Apps on Laravel 10/11 with an 8.1/8.2 floor pin you to symfony/config 6.4/7.x — workable (6.4 is LTS, still patched), but you'd be adopting on the deprecated fluent-builder path, and the surrounding docs/tutorials are split across three generations. Decide this up front; it's the single most likely reason this evaluation gets reversed later.
• You need to influence the roadmap. Issues and PRs live in the symfony/symfony monorepo; this repo is an automated split. We are a consumer, not a stakeholder. If config semantics are core IP, budget for a wrapper layer that isolates us.
• You're sensitive to version churn: fast patch cadence is a maturity signal and a maintenance tax — expect periodic minor upgrades and pin deliberately. Also treat the "Dependents: 0" figure as unreliable (an artifact of the monorepo split, since FrameworkBundle clearly depends on it); validate real adoption via Packagist before quoting it in a business case.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a free, MIT-licensed, battle-tested configuration library from Symfony — the component that underpins configuration for one of the two dominant PHP frameworks, with a funded foundation, continuous patch releases across an LTS line, and a decade-long track record. It lets us define a strict, documented schema for how our product is configured, then load it from YAML/XML/INI/database, apply defaults automatically, and reject bad input with precise error messages — instead of building and maintaining that machinery ourselves. That directly reduces support load from misconfiguration and shortens onboarding for self-hosted and enterprise customers. The trade-off is honest: it's a genuine engineering dependency requiring integration work in a Laravel codebase, and its latest major requires PHP 8.4, so we'd initially adopt on the 7.x line. Recommendation: adopt for nested, customer-facing config surfaces only, and keep simple app settings on Laravel's native config.

To engineering (summary): Adopt symfony/config as the schema/validation layer for our non-trivial config, not as a replacement for config(). Use TreeBuilder/ArrayNodeDefinition to declare a typed tree (scalars, enums, prototyped arrays, canBeEnabled/canBeDisabled folding), loaders to accept multiple formats, and ConfigCache with resource tracking for invalidation. Standardize on the PHP array config format, not the fluent builder — upstream deprecated the fluent format in 8.0 and is investing in array shapes and generated config/reference.php, and ArrayShapeGenerator gives us PHPStan-ready types for free. Scope it behind our own thin interface so the Symfony types don't leak into domain code, which is also our hedge if we ever need to swap it out. Expect to pin versions per PHP floor and to track the monorepo for changes, since this split repo has no independent roadmap.