This commit introduces a mechanism for validators to return early once
the validation outcome is determined, rather than evaluating all child
validators.
The ShortCircuit validator evaluates validators sequentially and stops
at the first failure, similar to how PHP's && operator works. This is
useful when later validators depend on earlier ones passing, or when
you want only the first error message.
The ShortCircuitCapable interface allows composite validators (AllOf,
AnyOf, OneOf, NoneOf, Each, All) to implement their own short-circuit
logic.
Why "ShortCircuit" instead of "FailFast":
The name "FailFast" was initially considered but proved misleading.
While AllOf stops on failure (fail fast), AnyOf stops on success
(succeed fast), and OneOf stops on the second success. The common
behavior is not about failing quickly, but about returning as soon as
the outcome is determined—which is exactly what short-circuit
evaluation means. This terminology is familiar to developers from
boolean operators (&& and ||), making the behavior immediately
understandable.
Co-authored-by: Alexandre Gomes Gaigalas <alganet@gmail.com>
Assisted-by: Claude Code (Opus 4.5)
I ran the `bin/console spdx --fix` with different strategies for
different files. For most of the core classes, since they've been
drastically rebuilt, I've run it with the `git-blame` strategy, for for
the `src/Validators`, in which the API changed completely but the logic
remains the same, I use the `git-log` strategy.
Improves SPDX header linting to ensure consistent license metadata across
the codebase.
Key changes:
- Enforce deterministic tag ordering (License-Identifier, FileCopyrightText,
FileContributor) to ensure consistency, prevent merge conflicts, and
simplify code reviews
- Add contributor alias mapping to consolidate contributors with multiple
emails or name variations (e.g., "nickl-" → "Nick Lombard")
- Add --contributions-strategy option with "blame" (current code authors)
and "log" (all historical contributors) to support different attribution
philosophies
- Add optional path argument to lint specific files or directories
- Add --fix option to automatically correct header issues
Assisted-by: Claude Code (claude-opus-4-5-20251101)
The previous name was confusing as it focused on the implementation
detail (calling a callable) rather than what the validator actually
does. The new name "After" better conveys the validator's purpose:
validating the input after applying a transformation.
Assisted-by: Claude Code (Opus 4.5)
The name "Factory" better conveys the validator's purpose: dynamically
creating a validator at runtime based on the input value. "Lazy" was
misleading as it suggested simple deferred evaluation rather than
input-dependent validator construction.
Also renamed the constructor argument from `$validatorCreator` to
`$factory` for improved expressiveness.
Assisted-by: Claude Code (Opus 4.5)
The `findByPath()` method was failing to return results when using nested
dot-notation paths such as `user.email` or `items.1`. However, it’s returning
`null` instead of the expected result in some cases.
The root cause was a mismatch between how paths are stored vs searched:
- Storage: Validators like Key and Each create results where the path is stored
as a linked list. For `user.email`, the "email" result has `path="email"` with
`parent="user"`.
- Search (old): The method expected a tree structure where it would find a child
with `path="user"`, then search that child for `path="email"`. But no child
had `path="user"` - only "email" (with "user" as its parent).
The fix computes each result's full path by walking up the parent chain and
compares it against the search path. Also converts numeric strings to integers
when parsing paths (e.g., `items.1` → `['items', 1]`) since array indices are
stored as integers.
While working on this fix, I also realised that to expose the result's status,
it’s best to use `hasFailed()` instead of `isValid()` in `ResultQuery`, since
users will mostly use results when validation failed, not when it passed.
Assisted-by: Claude Code (Opus 4.5)
We tried using `mkdocs-nav-weight` but it turned out quiet limited. Not
only we have to add specific frontmatter to the Markdown files, but we
could also not hide and sort directories.
This commit introduces awesome-pages, which allows us to customize the
order of pages and not list the content of the "validators" directory in
the left menu.
This commit introduces REUSE compliance by annotating all files
with SPDX information and placing the reused licences in the
LICENSES folder.
We additionally removed the docheader tool which is made obsolete
by this change.
The main LICENSE and copyright text of the project is now not under
my personal name anymore, and it belongs to "The Respect Project
Contributors" instead.
This change restores author names to several files, giving the
appropriate attribution for contributions.
The documentation was quite outdated after the many changes I made in
the main branch. This commit will make sure it's up-to-date.
I'm also creating a "Placeholder pipes" documentation, so there's not
too much content in the "Feature guide"
Assisted-by: Zed (devstral-2:123b)
We used to have those to preserve the order of the pages when generating
the documentation with MkDocs. This commit introduces the
`mkdocs-nav-weight`, that allows us to make that order without having
those prefixes.
This allows someone who wants to learn more about Validation to have a
more linear inflow of information.
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
We have seen users that want to change the default behavior of parameter
stringifier:
* Change the depth level shown from an array.
* Change the number of elements shown from an array.
* Not add quotes to some parameters.
Because of that, this commit will allow users to customize the parameter
stringifier.
This commit will also update the documentation to instruct how to
customize it.
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
The constructor of "Factory" has three arguments and, even though none
of them are needed, they are all required. Those arguments allow users
to customize the namespaces of rules and exceptions, and also to define
a callable that will translate the template messages.
This commit will remove those parameters from the constructor of
"Factory," and create methods that will allow users to customize the
namespaces and the translator.
The methods that this commit will create will not change the state of
"Factory," but they will create a clone with the customizations. It is
imperative that the "Factory" is immutable. Since the "Factory" is a
Singleton, allowing it to change could cause unexpected behaviors.
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
The only reason why those templates are static is so users can overwrite
the exception messages. That was useful when we didn't have a handy
translator, but now that we can define a translator through the Factory,
this is not needed anymore.
Besides, having those properties public adds complexity to the code.
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
The documentation about custom rules does not specify that creating an
exception for the rule is necessary. This commit will add that to the
documentation with an example to make it explicit.
Co-authored-by: Henrique Moody <henriquemoody@gmail.com>
The current documentation is hosted via GitHub pages rendered by
"Couscous". Every time we need a new version of the documentation
published we need to manually execute the "couscous".
This commit reorganize the documentation to be published to
"Read the Docs" because it will also allow us to have documentations per
version of the library most importantly provider a search field for the
documentation.
The documentation will be then published on:
https://respect-validation.readthedocs.io/
Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
