Config Laravel Package

Technical Evaluation

Architecture fit

symfony/config is a framework-agnostic library that solves a problem Laravel applications consistently handle badly: validating, merging, and documenting structured configuration from heterogeneous sources. It is not a Laravel replacement for config/ — it is a schema layer you place around a bounded configuration domain.

Two namespaces are relevant to us:

• Config\Definition — TreeBuilder, NodeBuilder, ArrayNodeDefinition, Processor. This is the high-value half: declarative schema, defaults, required/enum/numeric constraints, canBeEnabled()/canBeDisabled() semantics, deep-merge rules, and YamlReferenceDumper/ArrayReferenceDumper for auto-generated config reference docs.
• Config\Loader + ConfigCache — FileLocator, YamlFileLoader/PhpFileLoader/XmlFileLoader, DelegatingLoader, and resource-tracked caches (FileResource, GlobResource, ReflectionClassResource, ComposerResource). The resource-tracking cache is genuinely differentiated: Laravel's config:cache is all-or-nothing, whereas ConfigCache invalidates on specific file/class/composer changes.

Where it fits for us: package/module configuration with a public contract, a multi-source settings layer (file + env + DB), and enterprise deployments that need a published, validated config reference. It does not fit as a general-purpose application config store — Laravel's Repository plus env() is the right tool at the app layer.

Integration feasibility

Composer-installable, MIT, no service provider required, no container coupling. Constraints to verify before commit:

• The component requires symfony/filesystem and symfony/deprecation-contracts; YAML/XML support is opt-in via symfony/yaml/ext-dom. If we only need PHP-array or DB-sourced config, the footprint stays small.
• PHP floor is the binding constraint. The 8.x line requires PHP ≥ 8.4 (#60639). Laravel 11/12 projects routinely run 8.2/8.3. We must target ^7.4, which is the LTS line — see Operational Impact.
• Env-var interpolation is not in this package. EnvConfigurator/EnvPlaceholderParameterBag live in symfony/dependency-injection. If we want env placeholders resolved, we wire that ourselves or accept literal values.
• Symfony 8.0 removed the fluent PHP config format and deprecated config builder generators (#62092, #62135). Neither matters for our use case, but it signals the PHP-config API is churning — another reason to stay on 7.4.

Technical risk

• Metrics distortion. Dependents: 0 and Stars: 4276 are artifacts of the read-only split-repo model: real usage and stars accrue to symfony/symfony, and downstream dependents are counted against symfony/framework-bundle, not this repo. The 54.7 composite score under-weights a component with effectively universal PHP-framework adoption. Do not let this number drive a reject decision.
• Cache-coherency risk. Resource tracking covers files and classes, not env vars or DB rows. A DB-backed settings layer will silently serve stale processed config unless we add our own invalidation key.
• Upgrade-fragility. #61808 ("incorrect serialized data mangling") and #61727 (__sleep → __(un)serialize) mean cached node graphs are not upgrade-safe — deploys must flush the config cache.
• DSL learning curve. The TreeBuilder closure DSL is terse and unlike anything in the Laravel ecosystem; review quality degrades without a convention document.

Key questions

1. Is the target domain a package/module contract (strong fit) or app-wide settings (weak fit — stay with config/)?
2. Do we actually need multi-format loading, or is PHP-array/DB only? Dropping YAML/XML removes two optional dependencies and an XSD maintenance burden.
3. What is our PHP version floor across the fleet? If any production target is < 8.4, the decision is 7.4 LTS and we should say so explicitly.
4. Does anyone need the generated config reference (config/reference.php-style output) for customer-facing docs? That is often the real ROI.
5. Build vs. buy: nette/schema is lighter but the Symfony component's resource tracking and dumpers have no close equivalent.
6. Who owns the schema long-term — the platform team or the package maintainer?

Integration Approach

Stack fit

Adopt as a library inside a bounded module, layered alongside Laravel's config:

• Keep config/*.php and Config::get() untouched for framework and app wiring.
• Introduce symfony/config for one domain — recommended first candidate: a first-party package's configuration, or a tenant/settings module where the schema is the contract.
• Expose the processed result through a small Laravel service provider that binds a typed DTO (or an array) into the container. Consumers never touch TreeBuilder.

Migration path

1. Spike (3–5 days). Model the chosen domain's current config as a TreeBuilder schema; load existing values through the loader; diff processed output against current runtime values. Success criterion: byte-identical effective config plus better error messages on invalid input.
2. Shadow mode (1 sprint). Run the schema in CI as a validation command (php artisan config:validate-module) against real configs without changing runtime behaviour. This surfaces merge-semantics surprises cheaply.
3. Cutover one domain. Bind the processed config in the provider, add ConfigCache under storage/framework/cache/, and gate the old path behind a config flag for one release.
4. Generalize. Only after step 3 is stable for a full release cycle should we template the pattern for other domains.

Compatibility

• Pin symfony/config ^7.4 with an explicit comment that 8.x is blocked on PHP 8.4. Add a Composer constraint check in CI.
• Verify symfony/filesystem and symfony/deprecation-contracts do not conflict with Laravel's existing Symfony constraints (typically ^7.x — compatible).
• Confirm symfony/yaml is only added if YAML loading is in scope.
• Test against Octane: ConfigCache writes on first boot; under Octane the cache must be warmed at deploy, not lazily per worker.

Sequencing

Schema definition → loader wiring → cache layer with explicit invalidation key → CI validation command → provider binding → docs/dumper output. Do the cache layer before the provider binding; retrofitting invalidation after consumers depend on the values is materially more expensive.

Operational Impact

Maintenance

Upstream is the Symfony core team, with a six-month release cadence and a published support policy. The 7.4 LTS line is the anchor: ~3 years of bug fixes and ~4 years of security fixes from release. That is a stronger support horizon than most packages we carry, and it aligns with the PHP 8.2/8.3 reality of our fleet. Cost to us is version-bump cadence plus a mandatory config-cache flush on every deploy.

Support

No commercial support, no vendor escalation path — community issues route to symfony/symfony. Acceptable for infrastructure-grade libraries with LTS windows, but it means we own the integration layer and the DSL conventions. Budget roughly 0.1–0.2 FTE of ongoing ownership, concentrated on schema review.

Scaling

Tree processing is CPU-bound and happens once per boot; with ConfigCache the steady-state cost is a filemtime/hash check. Warm the cache at deploy time and the runtime cost is negligible. The risk vector is not throughput — it is cache-coherence across horizontally scaled workers when config sources change outside the tracked resources.

Failure modes

Ramp-up

Two developers need fluency in TreeBuilder/NodeBuilder. Realistic curve: 1–2 days to read, ~1 week to author a non-trivial schema confidently, 2–3 weeks to review others' schemas well. Mitigate with a short internal convention doc (node naming, info() usage, when to use canBeEnabled(), required-vs-default rules — note 8.x now forbids a node having both isRequired() and defaultValue(), so write the convention to be forward-compatible) and one reference schema checked into the repo.

Verdict framing for the decision record: adopt, scoped to one domain, pinned to ^7.4 LTS, with a pre-committed review after one release cycle. The 54.7 composite score reflects split-repo measurement artifacts, not package quality; the binding constraints are the PHP 8.4 floor on 8.x and the absence of env-placeholder handling outside DependencyInjection.