Skip to content

feat!: migrate to respect/validation 3 - #30

Open
awurth wants to merge 11 commits into
6.xfrom
feat/respect-validation-3
Open

awurth wants to merge 11 commits into
6.xfrom
feat/respect-validation-3

Conversation

@awurth

@awurth awurth commented Sep 4, 2026

Copy link
Copy Markdown
Owner

Migrates the library to respect/validation 3.x for the 6.0 release.

Runtime

  • Respect\Validation\Validatable no longer exists upstream. Every rule type is now Respect\Validation\Validator, imported as RespectValidator because of the collision with this package's own Awurth\Validator\Validator.
  • Asserter no longer catches an exception. It wraps the rules in a ValidatorBuilder, calls validate($subject, $templates) and converts the resulting ResultQuery messages into failures — respect 3 returns a result instead of throwing, so the try/catch is gone entirely.
  • Respect's synthetic __root__ composite entry (emitted whenever a node has several failing children) is dropped, so failure counts stay comparable to 5.x.
  • respect/validation: ^3.1.1. The patch component is deliberate: 3.1.1 carries the deep-path and __root__ template-cascading fixes this library's message flattening depends on, and ^3.1 would admit 3.1.0.

Breaking for consumers

  • Custom message keys are now respect validator ids. Simple rules keep their key (notBlank, alpha, between), composed ones change: length becomes lengthGreaterThanOrEqual.
  • Rules removed or resignatured upstream must be rewritten, V::length(min: 6) to V::length(V::greaterThanOrEqual(6)) most notably.
  • Failure counts and rule names for nested and iterating rules changed, since respect 3 reports each failing rule of each child rather than one message per key.

docs/upgrading-from-5.md covers all of it, linked from both the README and the docs index.

Bug found on the way

Flattening respect's message tree dropped sibling failures whenever integer keys collided — an each() over a list where one item fails several rules and another fails one returned two failures instead of three. Fixed in dcd1db1 with a regression test; 5.x had a related latent defect (a nested array could reach ValidationFailure as a message), which is why the PHPStan baseline shrank from 11 entries to 9.

Verification

just test — 18 tests, 49 assertions, green. just lint — CS Fixer, Rector and PHPStan level 10 all green. composer update --prefer-lowest --prefer-stable resolves respect/validation 3.1.1 and the suite passes there too.

Note

docs/superpowers/plans/2026-09-03-respect-validation-3-migration.md is the implementation plan this branch was executed from. Drop that commit if you would rather not keep it in the repository.

🤖 Generated with Claude Code

awurth and others added 11 commits September 4, 2026 17:43
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Respect's each() reports failing items with integer message keys.
PHP silently canonicalizes a decimal-integer string array key back
to int, so casting at the array-assignment site was a no-op and the
int reached ValidationFailureFactory::create()'s ?string $ruleName
parameter, throwing under strict_types. Cast where the value is
actually consumed instead.
flattenMessages() renumbered array-valued branches into the accumulator
via spread, then let a later integer-keyed sibling overwrite one of
those renumbered slots instead of appending — silently dropping
failures for each()/all() rules once a nested branch had more than one
message. Merge nested results entry by entry instead: string keys
assign, integer keys append.
- getRuleName()/messages docs claimed the respect id is "lowercased short
  class name"; Id::fromValidator() uses lcfirst(), not strtolower(), and
  each()/key() don't report a rule id at all (positional index / array
  key) — corrected in failures.md, options.md and upgrading-from-5.md
- extended the Message keys diff in upgrading-from-5.md with the renames
  the Rules section implies but never spelled out (notFalsy, notSpaced,
  undefOr*, nullOr*), verified against a live 2.x install since these
  wrappers didn't key by their own name in 2.x either (generic
  "validator" key)
- softened "the API is unchanged" to the shape being unchanged, since
  each()/key() failure counts and keys did change; noted in CHANGELOG
- noted respect 3's new production dependencies (php-di, psr/container,
  respect/string-formatter, respect/stringifier, two polyfills) in the
  Requirements section
- linked the upgrade guide from the README's 6.x doc list
- fixed CHANGELOG's respect/validation version (3.0 -> ^3.1.1) and the
  options.md messages table row/alignment
- fixed AGENTS.md's claim that global functions are called fully
  qualified; the fixer config and every src/ file say otherwise
… wrong

flattenMessages() discards a child's own key in the array branch: an
item's position (each()) or array key (key()) survives as the rule
name only when that child failed a single rule. As soon as one child
fails several rules, its key is thrown away and the whole flattened
list is renumbered by running position instead — verified against a
mix of single- and multi-rule key() children. Corrects failures.md,
options.md and upgrading-from-5.md, which all stated the wrong
unconditional version of this. Also hardens the each()/length
regression test to assert the actual rule names instead of only the
failure count, which would pass on three duplicated messages.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant