Validator Es Laravel Package

Technical Evaluation

Architecture fit
ajgl/validator-es is a framework-agnostic PHP library exposing one contract — ValidatorInterface::isValid(mixed $value): bool — with five concrete validators (DNI, NIE, IdCard, CCC, Spanish IBAN) plus checksum calculators added in 0.1.3. It is stateless, has no runtime dependency on Laravel, no service provider, no config, and no I/O, so it slots underneath our validation layer rather than into our architecture. That is the right shape for a TPM: it is a narrow capability (Spanish code format validation), not a platform dependency, and it is trivially replaceable. The only framework coupling upstream is a Symfony container registration (0.1.1) that we do not need; Laravel users get nothing out of the box.

Integration feasibility
Composer install plus a wrapper is the whole job. There is no native Laravel Rule, no validation message, no FormRequest support, and no Validator facade hook, so engineering owns approximately one thin rule class per code type, translated error copy, and test vectors. That is a small, well-bounded piece of work — days, not a sprint, for a team already fluent in Laravel validation. The main feasibility caveat is version resolution: 0.1.8 dropped PHP 8.1, and 0.1.7 added Symfony 8.x support while removing thecodingmachine/safe:^2, so the dependency graph should be resolved against our actual PHP and Laravel versions before committing.

Technical risk
Risk concentrates in maintenance and correctness, not performance. Adoption is effectively nil (1 star, 0 dependents), there is a single maintainer, and there is no visible CVE or security-review track record — acceptable for a checksum helper, not acceptable for anything a regulator or auditor will inspect. Functionally, this is format and checksum validation only: no existence checks, no CIF/NIF (the ID most B2B Spanish onboarding actually needs), no passports, no non-Spanish IBANs. The failure mode we must design against is a stakeholder reading "we validate Spanish IDs" as identity verification. MIT licensing and a small surface area make fork-and-own a viable escape hatch, which caps the downside.

Key questions

• Which codes are in scope — DNI, NIE, combined IdCard, CCC, Spanish IBAN — and is CIF/NIF required (it is absent)?
• Is format/checksum validation sufficient, or does the flow need existence verification via a KYC or bank API?
• Does any downstream process treat a passing validation as proof of identity, and who corrects that expectation?
• What PHP/Laravel versions are in production, and does 0.1.8 resolve cleanly against them?
• Who owns the Laravel wrapper, error messages, and regression test vectors?
• What is the documented fallback if upstream stalls — fork, swap to an alternative, or inline the checksum logic?
• Are there existing Laravel or Symfony constraints that already cover any of these codes, avoiding a new dependency entirely?

Integration Approach

Stack fit
Integrate behind Laravel's validator, never by calling the package directly from controllers. Recommended shape: one rule class per code (e.g. SpanishDniRule, SpanishNieRule, SpanishIdCardRule, SpanishCccRule, SpanishIbanRule), each implementing ValidationRule and delegating to the corresponding validator, returning Laravel-native failures with our own message keys. For non-request paths — imports, queue jobs, API ingestion, back-office tooling — call the same rules or a small SpanishCodeValidator service so behaviour is identical everywhere. A single wrapper namespace (e.g. App\Validation\Spanish) becomes the swap point if we ever replace the library.

Migration path
Phase 1: spike one validator (IdCard is the best pilot — it exercises both DNI and NIE paths) on a low-risk form, with unit tests for known-good and known-bad values. Phase 2: build the full rule set, add translations (Spanish and English), register them in the relevant FormRequest classes, and replace any existing ad-hoc regex or checksum code. Phase 3: update API docs and error catalogues, add the codes to any data-quality monitoring, and brief support on the new rejection messages. Rollback is cheap: the rules are isolated and stateless, so reverting is deleting five classes and their FormRequest references.

Compatibility
Confirm the target app runs PHP 8.2 or later (8.1 was removed in 0.1.8) and that Composer resolves the package alongside our Laravel and Symfony-adjacent dependencies — the changelog shows active Symfony 7.x/8.x churn, which can ripple into a Laravel app via shared transitive packages. The optional thecodingmachine/safe constraint changed between 0.1.6 and 0.1.7, so pin an exact version and lock it. Wrap everything in application CI so an upstream bump cannot silently alter validation outcomes.

Sequencing

1. Product and compliance agree the scope: which codes, format-only, and explicit wording that this is not identity verification.
2. Engineering resolves the dependency in a branch and confirms PHP/Laravel compatibility.
3. Build the pilot rule and test vectors, including deliberately tricky inputs (lowercase NIE prefixes, whitespace, leading zeros, invalid check letters, non-Spanish IBANs).
4. Review results with the requesting stakeholder, then fan out to the remaining rules and translations.
5. Ship behind the normal release process with a short note in the runbook; no feature flag needed given the blast radius.
6. Schedule a six-month re-evaluation of upstream health (releases, issues, dependents) as a low-cost maintenance checkpoint.

Operational Impact

Maintenance
Ongoing cost is low but not zero. Expect to own the wrapper, translations, and tests indefinitely; the upstream library itself should need little attention. Pin the version, avoid ^ ranges, and treat upgrades as deliberate changes gated by our own test vectors rather than routine composer update churn. The realistic long-term scenario is that upstream goes quiet and we either keep using a frozen, working version or vendor the ~small amount of checksum logic into our codebase — a half-day job, which is why the maintenance risk is tolerable.

Support
Support surface is limited to user-facing rejection messages and occasional disputes ("my DNI is valid but the form rejected it"). Two mitigations: (1) write error copy that explains the expected format rather than just saying "invalid", and (2) maintain a documented list of the exact rules applied so support can triage without engineering. There is no vendor to escalate to — the upstream project is self-service with a single maintainer — so internal ownership must be explicit and named.

Scaling
Effectively a non-issue. Validation is pure CPU on short strings with no allocation pressure, no network calls, and no shared state, so it disappears in profiling against any real request. It scales linearly and horizontally with the app and adds no operational dependency to deploys, containers, or infrastructure.

Failure modes
The realistic failure modes are behavioural, not infrastructural: (a) false rejections if real-world Spanish identifiers use formats the package does not accept — the highest-impact risk, mitigated by testing against a sample of production data before enabling on existing records; (b) false confidence if business stakeholders or downstream systems treat a pass as verified identity — mitigated by explicit wording in specs, API docs, and error messages; (c) silent behaviour change from an unpinned upstream bump — mitigated by exact version pinning and CI tests; (d) dependency resolution breakage during framework upgrades, given the upstream's active Symfony version churn — mitigated by keeping the wrapper thin so removal is trivial. There is no runtime crash or performance failure mode worth planning for.

Ramp-up
Onboarding cost is minimal. A developer unfamiliar with the package needs the README plus the wrapper classes and tests to be productive in well under an hour; the single-method interface means there is nothing to learn about the library itself. The real ramp-up investment is domain knowledge — what DNI, NIE, CCC, and Spanish IBAN actually are, and why format validation differs from verification — and that knowledge should live in the wrapper's docblock and the team runbook so it is not relearned every time the feature is touched.