RFC: Split `ValidatorBuilder` responsibilities into separate interfaces
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 6k
- Forks
- 773
- Avg merge
- 10h 6m
- Merged PRs (30d)
- 17
Description
Context
ValidatorBuilder currently has several distinct responsibilities mixed
into one surface:
- Composing a chain of validators (
with,__call,__callStatic,
getValidators). - Running the chain against an input and returning a value (
validate,
isValid). - Running the chain and throwing on failure (
assert,check).
Anything that depends on ValidatorBuilder today depends on the full
surface, even when it only needs one of these capabilities.
Proposal
Extract the consumer-facing capabilities behind narrower interfaces. The
class keeps implementing all of them — this is about the public contract,
not internal structure.
Naming candidates
| Interface | Methods | Behavior |
|---|---|---|
Validatable |
validate, isValid |
Non-throwing, returns a value |
Assertable |
assert |
Throws on failure, full evaluation |
Checkable |
check |
Throws on failure, short-circuit |
Composition (with, __call, getValidators) is intentionally left out —
it belongs to the implementation, not a shared contract.
evaluate and evaluateShortCircuit are already covered by the existing
Validator and ShortCircuitable interfaces.
Naming regret
While we're touching this area: after using the library more as a client,
I've come to think ValidatorBuilder was the wrong name. Validator
would have fit it better — what users actually hold and call is a
validator, not a builder. The existing Validator interface would then
have been better named Evaluable, since evaluate() is its only
contract.
Renaming isn't part of this RFC, but it's worth flagging as context for
how we pick names going forward.
Non-goals
- Renaming
ValidatorBuilderorValidator. - Splitting the class into multiple classes.
- Breaking the fluent API.
Drafted with assistance from Claude; reviewed and edited by me before posting.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the ValidatorBuilder class and the existing Validator and ShortCircuitable interfaces, then compare the proposed Validatable, Assertable, and Checkable contracts with the current methods. The work is done when the narrower interfaces reflect the agreed responsibilities, ValidatorBuilder implements them, and the fluent API and stated non-goals remain unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- backend-api-design
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100