Options Resolver Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Synergy: Seamlessly integrates with Laravel’s configuration system (config/, env(), app() bindings) and service containers, enabling declarative validation for service configurations (e.g., queues, databases, APIs).
• Component-Based Design: Lightweight (~10KB) and dependency-free (except PHP core), making it ideal for modular Laravel applications or standalone packages.
• Validation as Code: Replaces imperative checks (e.g., isset(), is_array()) with declarative schemas, reducing cognitive load and improving maintainability.
• Nested Structure Support: Handles complex configurations (e.g., ['database' => ['ssl' => ['cert' => '...']]]) via recursive resolution, critical for Laravel’s multi-layered configs (e.g., config('database.connections.mysql')).

Integration Feasibility

• Laravel Service Providers: Bind resolvers to the container for global reuse:

  $this->app->singleton(OptionsResolver::class, fn() => new OptionsResolver());
  

• Configuration Caching: Works with Laravel’s configuration caching (config:cache) since resolvers are runtime-evaluated (no static overrides).
• Environment Awareness: Supports dynamic defaults via closures (e.g., fn() => env('API_TIMEOUT')), aligning with Laravel’s .env system.
• Package Compatibility: No conflicts with Laravel’s core or popular packages (e.g., laravel/framework, spatie/laravel-package-tools).

Technical Risk

Key Questions

1. Prioritization:

   • Which 3–5 Laravel services (e.g., payment gateway, queue workers) will yield the highest ROI from validation?
   • Should we start with nested configs (e.g., database SSL) or flat configs (e.g., API timeouts)?

2. Implementation:

   • Should resolvers be globally scoped (container-bound) or service-specific (e.g., PaymentGatewayResolver)?
   • How will we cache resolved configs to avoid redundant validation in high-traffic endpoints?

3. Migration:

   • Which legacy configurations (e.g., config('old_driver')) should be deprecated first?
   • How will we backfill validation for existing configs without breaking changes?

4. Monitoring:

   • Should we log validation failures to a central system (e.g., Sentry) for incident tracking?
   • How will we measure impact (e.g., % reduction in config-related bugs)?

5. Scaling:

   • Can resolvers be shared across microservices (e.g., via a shared package)?
   • How will we handle dynamic resolvers (e.g., runtime-generated configs for serverless functions)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Configuration: Replace array_replace_recursive in config/array.php with OptionsResolver for structured validation.
  • Service Containers: Bind resolvers to the container for dependency injection (e.g., resolve(OptionsResolver::class)).
  • Packages: Use resolvers in custom packages (e.g., laravel-notification-service) to enforce consistent configs.
• Symfony Compatibility:
  • Works alongside Symfony’s full stack (e.g., HttpClient, Messenger) if Laravel uses Symfony components.
  • Avoids conflicts with Symfony’s OptionsResolver (same package, identical API).
• PHP Extensions:
  • Requires PHP 8.2+ (for v7.4.x) or PHP 8.4+ (for v8.0.x). Use polyfills or composer scripts to enforce version constraints.

Migration Path

1. Phase 1: Pilot Services (2–4 weeks)

   • Target high-risk services (e.g., payment processing, queue workers).
   • Replace manual validation with resolvers without changing public APIs.
   • Example:

     // Before
     if (!is_numeric($config['timeout'])) {
         throw new \InvalidArgumentException('Timeout must be numeric.');
     }
     // After
     $resolver->setAllowedTypes('timeout', ['int', 'null']);
     $config = $resolver->resolve($config);
     

2. Phase 2: Package Integration (4–6 weeks)

   • Refactor custom packages to use resolvers for configuration contracts.
   • Example:

     // In a custom package
     $resolver = new OptionsResolver();
     $resolver->setRequired(['driver']);
     $resolver->setAllowedValues('driver', ['mail', 'slack']);
     return $resolver->resolve($config);
     

3. Phase 3: Global Adoption (6–8 weeks)

   • Replace Laravel’s core config validation (e.g., config/array.php) with resolvers.
   • Add deprecation warnings for legacy configs (e.g., config('old_driver')).
   • Example:

     $resolver->setDeprecated('old_driver', '2.0', 'Use `new_driver` instead.');
     

4. Phase 4: Optimization (Ongoing)

   • Cache resolved configs in high-traffic services (e.g., API gateways).
   • Benchmark performance and adjust resolver complexity (e.g., avoid over-nesting).

Compatibility

Sequencing

1. Dependency Setup:

   • Add to composer.json:

     "require": {
         "symfony/options-resolver": "^7.4"
     }
     

   • Run composer update.

2. Resolver Creation:

   • Create a base resolver (e.g., app/Resolvers/ConfigResolver.php):

     use Symfony\Component\OptionsResolver\OptionsResolver;
     
     class ConfigResolver {
         public function __construct(private OptionsResolver $resolver) {}
         public function resolve(array $config): array {
             return $this->resolver->resolve($config);
         }
     }
     

3. Service Integration:

   • Bind resolvers to the container in a service provider:

     $this->app->singleton(OptionsResolver::class);
     $this->app->bind(ConfigResolver::class, fn($app) => new ConfigResolver($app->make(OptionsResolver::class)));
     

4. Validation Rules:

   • Define rules in service-specific resolvers (e.g., PaymentResolver, QueueResolver):

     $resolver->setRequired(['api_key', 'timeout'])
              ->setAllowedTypes('timeout', ['int', 'null'])
              ->setNormalizer('retries', fn($val) => max(0, $val));
     

5. Testing:

   • Write unit tests for resolver rules (e.g., PaymentResolverTest).
   • Test edge cases (e.g., nested invalid configs, deprecation warnings).

6. Rollout:

   • Start with non-critical services (