Weave Code
Options Resolver Laravel Package
symfony/options-resolver
Symfony OptionsResolver enhances array_replace with a robust options system: define required options, set defaults, validate types and values, and normalize inputs. Ideal for building configurable APIs, form components, and reusable libraries with strict option handling.
The Symfony OptionsResolver component is array_replace on steroids: it helps you define, validate, and normalize configuration arrays in a consistent way. Use it to build robust option systems for libraries and reusable services, with clear constraints and predictable defaults.
Features:
- Define required options and default values
- Validate options by type and allowed values
- Apply normalizers to transform options consistently
- Enforce option definitions with helpful error messages
- Support complex configuration with resolvers and closures
Frequently asked questions about Options Resolver
- How does Symfony OptionsResolver improve over Laravel’s built-in config() helper or Form Request validation?
- OptionsResolver adds structured validation (types, required fields, custom normalizers) and nested option handling, which Laravel’s config() or Form Requests lack. It’s perfect for reusable components where you need strict, declarative option definitions (e.g., third-party API clients or service configurations). For example, you can enforce that a `timeout` option must be an integer between 1–300, or normalize a string enum to a constant.
- Can I use OptionsResolver in Laravel’s Service Container to replace manual array_merge in service constructors?
- Yes. Bind the resolver as a singleton or per-request service, then resolve options in constructors. For example: `$this->app->singleton(OptionsResolver::class, fn() => new OptionsResolver());`. This replaces ad-hoc `array_merge` logic with validated, reusable configurations. Works seamlessly with Laravel’s DI, especially for services with complex nested dependencies.
- What’s the minimal setup to use OptionsResolver in a Laravel package?
- Install via Composer (`composer require symfony/options-resolver`), then define your options in a resolver instance. Example: `$resolver = new OptionsResolver(); $resolver->setDefaults(['timeout' => 30]); $resolver->setRequired(['api_key']);`. Use it in your package’s logic or bind it to Laravel’s container. No Laravel-specific bootstrapping is needed beyond Composer autoloading.
- Does OptionsResolver support Laravel’s Form Request validation pipeline?
- Yes. Use it to pre-process and validate incoming request data before Laravel’s validation runs. For example, normalize a `payment_method` string to a constant or validate nested `billing.address` structures. Inject the resolver into your Form Request’s constructor or use a service provider to resolve options dynamically.
- What Laravel versions and PHP versions does OptionsResolver support?
- OptionsResolver v7.4.x requires PHP 8.2+ (for union/intersection types), while v6.4.x supports PHP 7.4–8.1. Laravel 10+ (PHP 8.1+) works with v7.4.x, but for older Laravel (e.g., 9.x), use v6.4.x. Check your Laravel version’s PHP requirements first—OptionsResolver itself doesn’t enforce Laravel-specific constraints.
- How do I handle nested configurations (e.g., config('services.stripe.api_key')) with OptionsResolver?
- Use the `setOptions()` method for nested structures. Example: `$resolver->setOptions(['stripe' => ['api_key' => ['default' => null, 'required' => true]]]);`. This mirrors Laravel’s nested config format. For dynamic configs, bind the resolver to the container and resolve options via `$this->app->make(OptionsResolver::class)->resolve($inputConfig)`.
- Are there performance concerns with OptionsResolver in high-traffic Laravel apps?
- No. OptionsResolver is optimized for speed—resolution is O(n) and cached-friendly. For queue workers or high-throughput services, the overhead is negligible. If needed, pre-resolve options in a service provider or cache resolved configurations. Benchmark with your specific use case, but Symfony’s documentation confirms it’s suitable for production.
- Can I migrate from manual array_replace_recursive to OptionsResolver without breaking existing code?
- Yes, but refactoring is required. Replace `array_replace_recursive` calls with `$resolver->resolve($input)`. For nested arrays, use `setOptions()` to define structures. Test thoroughly, as OptionsResolver enforces strict validation (e.g., missing required fields will throw exceptions). Start with low-risk areas like third-party API clients.
- What alternatives exist for option validation in Laravel, and why choose OptionsResolver?
- Alternatives include Laravel’s `Validator` facade (for HTTP requests) or custom logic with `array_merge`. OptionsResolver stands out for reusable, non-HTTP configurations (e.g., service defaults, CLI commands). It’s more lightweight than full frameworks like Symfony’s DependencyInjection and integrates better with Laravel’s container than standalone validators.
- How do I test OptionsResolver in Laravel’s unit tests?
- Mock the resolver or use a test double to assert resolved options. Example: `$resolver = $this->createMock(OptionsResolver::class); $resolver->method('resolve')->willReturn(['timeout' => 30]);`. For integration tests, bind a test resolver to the container and verify resolved values. If testing Form Requests, assert that the resolver’s output matches expected normalized data before Laravel’s validation runs.
Weaver
How can I help you explore Laravel packages today?