Symfony OptionsResolver

The Symfony OptionsResolver component is array_replace on steroids. It lets you build a robust options system for methods and classes with required options, default values, type and value validation, normalization, and deprecation, replacing brittle hand-written array merging and manual checks.

You declare the shape of an options array once, defining defaults, allowed types and values, dependencies between options, and normalizers, then resolve any user-supplied array against that definition. Invalid, missing, or unknown options raise clear, specific exceptions, making it a common foundation for configurable libraries and components.

What You Get

• Declarative definition of defaults, required options, and allowed types or values
• Normalizers that transform option values, including based on other resolved options
• Lazy defaults and inter-option dependencies resolved on demand
• Clear, specific exceptions for missing, unknown, or invalid options
• Option deprecation support and nested options for structured configuration

Common Use Cases

• Validating and normalizing an options array passed to a configurable class or method
• Enforcing required options and allowed value or type constraints for a library’s public API
• Computing default option values lazily from other supplied options
• Deprecating options gracefully while guiding users toward replacements

Under The Hood

Architecture - OptionsResolver.php holds the configured schema: maps of defaults, required and defined options, allowed types, allowed values, normalizers, and deprecations. Calling resolve() walks the supplied array, applies lazy defaults and inter-option closures through an Options view, validates types and values, runs normalizers in dependency order, and throws typed exceptions from the Exception/ namespace for any violation. OptionConfigurator.php offers a fluent per-option builder.

Tech Stack - Pure PHP under the Symfony\Component\OptionsResolver namespace with PSR-4 autoloading and effectively no runtime dependencies, targeting modern PHP. It is distributed as a read-only subtree split of the symfony/symfony monorepo.

Code Quality - The repository includes a focused PHPUnit suite under Tests/ covering defaults, required options, allowed types and values, normalizers, lazy and dependent options, and deprecation, following Symfony’s strict coding standards and backward-compatibility promise; recent commit activity is lower simply because the API is stable and mature.

API Design - The API is compact and expressive: setDefaults, setRequired, setAllowedTypes, setAllowedValues, and setNormalizer read declaratively, and the closure-based Options view makes dependent defaults natural. This small, well-documented surface gives it a gentle learning curve.