Options Resolver Laravel Package

Technical Evaluation

Architecture fit. michel/options-resolver is a framework-agnostic utility for validating associative option arrays against a declared schema (required/optional keys, types, defaults, strict unknown-key rejection). It occupies the same architectural slot as Symfony's OptionsResolver, spatie/laravel-data DTO hydration, and PHP 8.1+ readonly classes with named arguments. It does not compete with Laravel's HTTP validator; it is a boundary-hardening tool for constructors, package config objects, action/job payloads, and SDK entry points. The fit is narrow but legitimate: teams writing shared internal packages or public SDKs where an array-shaped config must fail fast and loudly.

Integration feasibility. MIT license, Composer-installable, and apparently free of Laravel service-provider coupling — the cheapest possible integration surface. Expected effort for a spike is under a day. The blockers are evidentiary, not technical: zero stars, zero dependents, no visible docs, and no production usage to learn from.

Technical risk. High, concentrated in provenance rather than code:

• Bus factor 1. Single-maintainer package with no downstream users means no implicit regression testing and no community patching.
• Metadata anomaly. The listed last release date (2026-09-04) post-dates the evaluation window. Verify the actual Packagist tag, commit signature, and repository history before trusting the version string — a mismatch is a provenance red flag.
• No compatibility evidence. Unknown PHP floor, no confirmed Laravel 10/11/12 matrix, no CI badge, no coverage report.
• Supply-chain surface. A generic michel/ vendor namespace with no dependents is a plausible typosquat target; confirm the Git remote matches the Packagist entry.
• Semantic overlap. If the package is later abandoned, migration to Symfony OptionsResolver is straightforward but non-zero (different exception types and fluent API shape).

Key questions.

1. Does it support nested/recursive resolvers, and is there recursion-depth protection?
2. What exception hierarchy is thrown, and is it stable across minor versions?
3. What is the PHP version floor, and is strict_types enforced internally?
4. Is there a documented deprecation/BC policy, or is this a personal utility published as-is?
5. Does strict mode reject unknown keys by default, or opt-in?
6. Is there a security contact and disclosure process?
7. Measured cost versus Symfony OptionsResolver on a realistic nested schema?

Integration Approach

Stack fit. Install as a plain Composer dependency behind an internal adapter interface (e.g., App\Support\Options\Schema). No service provider, no config publishing, no facade. This keeps the package a swappable implementation detail rather than an architectural commitment.

Migration path. Introduce in exactly one bounded context — a single internal package's config object or one job-payload constructor — and nowhere else. Do not layer it under HTTP request validation; Laravel's validator and FormRequests remain the correct tool there. If the pilot holds, expand per-package rather than fleet-wide.

Compatibility. Pin an exact version (composer require michel/options-resolver:x.y.z), commit the lockfile, and add the package to our own CI matrix against the PHP and Laravel versions we actually run. Audit the source for global functions, constants, and any hidden framework assumptions before merging. Verify the tag against the upstream commit SHA.

Sequencing.

1. Day 1–2: source read + spike on a throwaway branch; enumerate edge cases (missing required key, wrong scalar type, nested array, null vs. absent).
2. Day 3–4: characterization tests written by us, not inherited from upstream, covering those cases and exception types.
3. Decision gate: if the package passes and the code is small, vendor or fork it under our GitHub org rather than depend on an unmaintained upstream. Reimplementation is plausibly 200–400 LOC — compare that cost honestly against indefinite fork maintenance.
4. Pilot: one non-critical service, two sprints, with a rollback to Symfony OptionsResolver pre-designed.
5. Expand only on evidence — zero incidents, and the owning team accepts fork stewardship.

Given a composite score of 17.6/100 and an opportunity score of 4.81, the default recommendation is do not adopt as an external dependency; treat it as reference material or vendor the source.

Operational Impact

Maintenance. Effectively zero upstream maintenance guarantee; we become the de facto maintainer on day one. Budget explicit ownership: a named team, a fork branch, and a quarterly review to decide whether to keep, upstream, or replace. Patch SLA is undefined and must be invented internally.

Support. No community, no Stack Overflow footprint, no documentation site. Every question routes to source code. Internal docs (schema DSL, exception handling, strict-mode semantics) are a prerequisite, not a nice-to-have.

Scaling. Runtime cost is negligible — array validation is microseconds against any I/O-bound request; scaling risk is organizational, not computational. The real scaling constraint is that every team touching the adapter needs the same internal docs and the same fork.

Failure modes.

• Uncaught or renamed exception types on a patch bump → wrap all calls and normalize to an internal exception.
• Unknown keys silently accepted if strict mode is opt-in and misconfigured → assert strict behavior in our own tests.
• PHP minor-version breakage with no upstream fix → fork is the only remedy.
• Packagist deletion or repo takedown → vendoring eliminates this entirely.
• Unbounded recursion in nested resolvers → cap nesting in our adapter.

Ramp-up. A mid-level engineer reads a fluent options API in 2–4 hours; without docs, add half a day for source reading. The owning team needs 2–3 days to stand up the fork, CI matrix, and characterization suite. Total onboarding cost is small in absolute terms — the concern is that this cost recurs for every team that adopts it, against a package with no ecosystem to amortize it.