Options Resolver Laravel Package

Product Decisions This Supports

• Standardizing configuration contracts across services and packages. OptionsResolver lets a team declare required options, defaults, allowed types/values, normalizers, and nested schemas in one place instead of scattering isset()/is_array()/is_numeric() checks. This is a foundational decision: it doesn't ship a user-facing feature, but it removes a recurring class of defects and support load.
• Build vs. buy for config/options handling. Build: bespoke validation helpers per service, inconsistently enforced and repeatedly rewritten. Buy: symfony/options-resolver — MIT, Symfony-maintained, mature (7.x/8.x lines), battle-tested by the framework ecosystem. The buy decision is low-risk: no licensing review, no vendor lock-in, and it is a small, dependency-light component. Adopt it as the internal default for option handling rather than green-lighting one-off validation code.
• Third-party integration reliability. Payment, messaging, storage, and API-client integrations fail most often on misconfiguration (wrong type, missing key, invalid enum). Declaring an option schema per integration converts silent misconfiguration into explicit, early errors — directly supporting reliability and incident-reduction goals.
• Reusable package / SDK strategy. If the roadmap includes extracting internal services into Composer packages, OptionsResolver provides the "public API" for package options: required fields, deprecation warnings, and safe defaults. This supports decisions to productize internal tooling and to set adoption/support expectations for consumers.
• Deprecation and migration planning. setDeprecated() plus normalizers/fallbacks supports phased configuration changes (e.g., renaming a driver option) without breaking existing deployments. This informs how aggressively the roadmap can ship breaking config changes and how much migration tooling to invest in.
• Environment and multi-tenant configuration. Lazy defaults via closures let the same resolver express per-environment or per-tenant behavior (debug, timeouts, feature flags) without duplicating config files — useful for decisions about environment parity and config sprawl.
• Where it should not drive decisions. It is not a user-input validator, not a form-validation layer, and not a serialization/DTO tool. Treating it as such would misallocate effort; those concerns belong to Laravel's validator or a data-transfer package.

When to Consider This Package

Adopt when:

• A service, integration, or package exposes more than ~5 options, or any nested option structure (e.g., database.ssl.cert).
• Configuration is consumed by code you don't control at runtime — third-party SDKs, queue workers, API clients — where a bad value causes downtime rather than a caught test failure.
• You are publishing a package or SDK and want a stable, self-documenting options contract with deprecation paths.
• You need normalization (string → enum, scalar → array) or conditional defaults, not just presence checks.
• You want one consistent pattern across teams instead of per-service validation utilities.
• You are on a supported PHP version (7.4.x line for older apps; 8.x line requires PHP 8.4 — note the major-version PHP floor before pinning).
• You're already in the Symfony/Laravel ecosystem where the component is a natural, low-friction dependency.

Look elsewhere when:

• Configuration is flat and trivial (a couple of keys, no validation) — a plain array merge is cheaper.
• The need is user-facing input validation — use Laravel's Validator/FormRequest; that is a different problem with different UX requirements.
• The need is typed data objects / serialization / casting — a DTO or data-mapping package is a better fit; OptionsResolver resolves arrays, not objects.
• Configuration is file- or schema-driven (YAML/JSON with external contracts) — a schema validator gives you better tooling and error reporting.
• Your dependency policy is strict or you're on an unsupported PHP version; verify the 7.x/8.x PHP floor against your runtime before committing.
• The pain isn't demonstrated — if there's no history of config-related bugs or tickets, the ROI case is weak and the added abstraction may not pay for itself.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed, Symfony-maintained component that standardizes how our services validate their configuration. It doesn't add a user-facing feature — it reduces a specific, recurring failure mode: services breaking in production because a config value was missing, the wrong type, or silently ignored. The business case is operational: fewer config-related incidents (especially in payment and integration paths), lower support load, and faster onboarding because configuration rules become explicit rather than tribal knowledge. Risk is low: mature package, permissive license, no vendor lock-in, incremental adoption. Recommendation: approve it as the internal standard for option handling and pilot it on one or two high-risk integrations before broad rollout.

For engineering leaders: OptionsResolver replaces hand-rolled validation with a single declarative API: required options, defaults, allowed types/values, normalizers, nested option sets, and deprecation warnings. Benefits are consolidation (one pattern instead of N bespoke helpers), earlier failure (misconfiguration surfaces at construction, not mid-request), and a clean migration path for config changes via setDeprecated(). Watch two things in planning: the major-version PHP floor (the 8.x line targets PHP 8.4; stay on 7.4.x otherwise) and scope discipline — it resolves option arrays, not user input or DTOs. Suggested rollout: pilot on the payment/integration config and one shared package, measure config-related incidents and time-to-configure, then codify as a team convention.

For developers: Define the contract once and let the resolver enforce it:

$resolver = new OptionsResolver();
$resolver->setRequired(['driver', 'timeout'])
         ->setAllowedTypes('timeout', ['int', 'null'])
         ->setAllowedValues('driver', ['mail', 'slack', 'sms'])
         ->setDefault('retries', 3)
         ->setNormalizer('retries', fn ($v) => max(0, (int) $v));

$options = $resolver->resolve($config); // throws with a precise message on bad input

Nested structures use a sub-resolver via setOptions() rather than nested setDefault() (the latter is deprecated in the 7.3 line and removed in 8.0). No more if (!is_numeric(...)) scattered through service providers.