Api Validator Laravel Package

Technical Evaluation

Architecture fit. Despite being filed under a Laravel/PHP package, eleven-labs/api-validator is not Laravel-native — it is a framework-agnostic schema library that validates PSR-7 requests against a Swagger 2.0 description, backed by justinrainbow/json-schema. Architecturally that makes it a contract-enforcement layer sitting in front of the application, not a replacement for Laravel's FormRequest/Validator stack. In a Laravel context this means inserting it as middleware, which requires a PSR-7 bridge (symfony/psr-http-message-bridge plus a PSR-7 implementation such as nyholm/psr7). That extra hop is the single biggest architectural fit consideration: Laravel hands you an Illuminate\Http\Request (Symfony HttpFoundation), not a PSR-7 message, so every request pays a conversion cost and every body-stream edge case (file uploads, chunked bodies, already-consumed streams) becomes our problem.

Integration feasibility. Feasible for a spike, questionable for a committed dependency. The library only supports Swagger 2.0 — not OpenAPI 3.x — which is the dominant spec version for any API designed in the last several years. If our specs are 3.x, this package is either unusable or requires a conversion step (spec downgrade) that introduces its own drift risk. The dependency on justinrainbow/json-schema is a positive: it is a mature, widely used validator, so the core validation semantics are trustworthy even if the wrapper is thin.

Technical risk. High, driven by project health rather than code quality:

• 24 stars, 0 dependents, "readme"-level maturity, Travis CI badges (a deprecated CI platform) — strong signals of an unmaintained or minimally maintained project.
• Single-vendor ownership (Eleven Labs, an agency) with no visible governance, release cadence, or roadmap execution on the promised RAML / API Elements support.
• PHP version and Laravel version constraints are unstated in the README and must be verified against our target runtime before any commitment.
• Swagger 2.0-only support is a strategic mismatch with where the industry (and likely our own specs) has moved.

Key questions to answer before adoption.

1. What PHP versions and Laravel releases are actually supported/tested? Is there a tagged release, or only master?
2. Are our source-of-truth specs Swagger 2.0 or OpenAPI 3.x? If 3.x, is conversion acceptable, or does this disqualify the package?
3. Does it validate responses as well as requests, and how are validation errors surfaced (exception type, error payload shape)?
4. How are $ref resolution, allOf/oneOf, formData/multipart, and non-JSON content types handled?
5. Is there caching of the parsed spec, or is the document re-parsed per request?
6. License and security posture — any known CVEs in the transitive dependency tree?

Integration Approach

Stack fit. The package belongs at the HTTP boundary as a middleware, with the Swagger document loaded once and cached (config-cached or a compiled/cached validator instance) rather than parsed per request. It should be positioned as a contract guardrail alongside — not instead of — existing Laravel validation. Runtime enforcement and CI-time contract testing are two distinct use cases; the second is lower-risk and delivers most of the value.

Migration path. Do not cut over directly. Sequence:

1. Dependency audit — confirm PHP/Laravel compatibility, resolve the Swagger-vs-OpenAPI version question, verify license and transitive security.
2. Spike — build a single middleware around the PSR-7 bridge validating one low-risk endpoint; measure per-request overhead and error ergonomics.
3. Shadow mode — run validation in log-only mode across a representative route group in staging, diffing results against existing FormRequest rules. This surfaces false positives (the main operational hazard) before they can break traffic.
4. Enforce selectively — enable blocking validation on stable, well-specified endpoints; expand only where shadow-mode noise is near zero.
5. Parallel evaluation — benchmark against actively maintained alternatives (league/openapi-psr7-validator, cebe/php-openapi, swagger-php) before locking in.

Compatibility. Two hard gates: (a) spec version — Swagger 2.0 only; (b) PSR-7 bridge compatibility with the current Symfony/Laravel HTTP stack. Note that the bridge converts the request body into a stream, and Laravel middleware ordering matters — validation must run before controllers consume input, and must not interfere with file uploads or php://input reads.

Sequencing. Treat this as a time-boxed evaluation, not an adoption. Run it in parallel with an assessment of maintained OpenAPI 3.x validators. If the alternative wins on compatibility, the spike cost is still repaid by the contract-testing pattern established.

Operational Impact

Maintenance. The dominant risk. Zero dependents and 24 stars imply effectively no community backstop; if the maintainer goes quiet (or already has), we own the code. Budget for an internal fork or vendored copy, plus a named owner. Any fork must track justinrainbow/json-schema upstream for security patches.

Support. Documentation is README-only — no cookbook, no error catalogue, no Stack Overflow footprint. Onboarding support will be internal-only; escalation to the vendor is unlikely to be responsive.

Scaling. Parsing and $ref-resolving a large Swagger document per request is a real latency and memory cost. Mitigation is mandatory spec caching and, ideally, pre-compiled validators. Validation itself adds CPU per request; at high throughput this needs measurement, not assumption. Large specs with deep $ref graphs are the worst case.

Failure modes.

• Fail-closed false positives — spec drift or over-strict schema blocks legitimate traffic. This is the highest-severity risk; it argues strongly for shadow mode first and a kill switch.
• Spec parse failure — a malformed or partially-resolved spec can fail at request time; needs fail-open/fail-closed policy decided explicitly and a health check on spec load.
• PSR-7 bridge mismatches — body stream consumption, multipart/file-upload handling, and content-type negotiation are classic breakage points.
• Silent drift — spec and implementation diverge in opposite directions; validation passes but the API is wrong (or vice versa). Requires spec-in-CI discipline.
• Abandonment — no upstream fixes for PHP/Laravel upgrades; the package silently becomes a blocker on framework modernisation.

Ramp-up. Low-to-moderate for engineers familiar with OpenAPI concepts; the PSR-7 layer and Swagger 2.0 (as opposed to OpenAPI 3.x) semantics are the friction points. Expect the team to spend more time on the bridge, caching, and error-surface design than on the validator itself.

Verdict. The high opportunity score (4.64) reflects a genuine gap — spec-driven request validation in PHP is under-served — but this package's low maturity, Swagger 2.0-only scope, and zero dependents make it a research spike, not a production dependency. Recommend: evaluate it as a reference implementation for contract-testing patterns, benchmark against a maintained OpenAPI 3.x validator, and only adopt with a fork-and-own commitment plus shadow-mode rollout.