Respect / Respect/Validation

RFC: Split `ValidatorBuilder` responsibilities into separate interfaces

Open
#1,789 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Discussion Enhancement
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 ValidatorBuilder or Validator.
  • Splitting the class into multiple classes.
  • Breaking the fluent API.

Drafted with assistance from Claude; reviewed and edited by me before posting.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.