We want to release version 3.0 as fresh as possible, without having to
maintain backward compatibility with the previous versions. Because that
version will be on for some time, we decided it will be best to support
only PHP version 8.5 or higher.
Acked-by: Alexandre Gomes Gaigalas <alganet@gmail.com>
We want to release version 3.0 as fresh as possible, without having to
maintain backward compatibility with the previous versions.
Acked-by: Alexandre Gomes Gaigalas <alganet@gmail.com>
We want to release version 3.0 as fresh as possible, without having to
maintain backward compatibility with the previous versions. Apart from
that, for some rules, it's impossible to be compatible with older
versions.
Acked-by: Alexandre Gomes Gaigalas <alganet@gmail.com>
I'm creating a workaround here, which is not exactly happy with, but
adding "uopz" as a dependency to run the tests make it harder for
developers, including myself.
The problem with the current approach is that the "expect()" calls
happen inside "tests/Pest.php". That means that when something fails, we
can't easily know which exact expectation has failed.
This commit will change the helper functions, and will make the tests
more verbose, but event with that, the developer experience is better.
I don't expect us to have more modes, hence a simple boolean value
should be enough for indicating the mode of the teamplate. Apart from
that, the name "inverted" woudln't always make sense, because if you
invert something that is inverted, it gets back to its original mode.
This commit will remove the `Mode` enum, and also improve the naming of
some methods in the `Result`.
There are a few cases in which we want to validate the object as a
whole, and that validation could be attached to the class as a PHP
attribute. This commit enables that capability and changes a few rules
to be class attributes.
This transformers will help transition from the current major version to
the next. In the current version, it's possible to call `allOf`,
`anyOf`, `noneOf`, and `oneOf` without any arguments or with only one,
and that doesn't make much sense.
There's no reason not to make this method public. It will actually be
easier for users to test their rules when they extend this class if this
method is public.
When nested-structural validation fails, it's challenging to identify
which rule failed from the main exception message. A great example is
the `Issue796Test.php` file. The exception message says:
host must be a string
But you're left unsure whether it's the `host` key from the `mysql` key
or the `postgresql` key.
This commit changes that behaviour by introducing the concept of "Path."
The `path` represents the path that a rule has taken, and we can use it
in structural rules to identify the path of an array or object.
Here's what it looks like before and after:
```diff
-host must be a string
+`.mysql.host` must be a string
```
Because paths are a specific concept, I added a dot (`.`) at the
beginning of all paths when displaying them. I was inspired by the `jq`
syntax. I also added backticks around paths to distinguish them from any
other value.
I didn't manage to fix a test, and I skipped it instead of fixing it
because I want to make changes in how we display error messages as
arrays, and it will be easier to fix it then.
Some templates were a bit confusing, and I would like to favour adding
the `{{name}}` at the beginning of the templates as it helps when
reading nested messages.
I also deleted the regression tests for issue #1348, because it's a
non-issue, actually. The best approach to that problem is indeed using
`When` insteaf of `OneOf`.
The `StandardQuoter` adds backticks around strings, which indicates that
it's not a simple string but a code. With this stringifier, we can add
quotes to placeholders directly into templates.
The standards `CompositeStringifier` from "respect/stringifier" has lots
of interesting stringifiers. However, this library is not 100% focused
on engineers. Someone could type a string that matches a callable, and
then you will overexpose the system.
This commit makes sure that callables are not interpreted as callables.
Because of how the validation engine works now [1], there's no reason to
keep adding names to each rule. Instead, create a single rule that
handles naming rules with a few other accessories. This change is not
necessarily simple, but it shrinks the `Rule` interface, and it's more
aligned with how the library works right now.
Personally, I think this API is much more straightforward than the
`setName()` method, as it's way more explicit about which rule we're
naming. Because of this change, the behaviour changed slightly, but it's
for the best.
Because of this change, I managed to remove a lot of code, but
unfortunately, it's quite a big-bang commit. It would be too complicated
to make it atomic since names are an intrinsic part of the library.
[1]: 238f2d506a
I've already changed the `ValidationException` so as not to let the file
and line from the Validator.php [1]. However, one could go even further
when creating more customizations on top of this library, and allowing
to customize the line could be very useful.
What motivated me making this change because it will be handy when I get
back to work on [Assertion][].
[1]: 75a9b8e94f
[Assertion]: https://github.com/Respect/Assertion
Because of how the validation engine works, there's no reason to keep
adding templates to each rule. Instead, creating a single rule that
handles templating rules will simplify the library greatly and shrink
the `Rule` interface.
Personally, I think this API is much more straightforward than the
`setTemplate()` method, as it's way more explicit which rule is being
templated.
The "NotBlank", "NotEmpty", and "NotUndef" rules do not display the
input in all cases and instead displays the string "The value". The
problem with that is that one doesn't see which value was passed, which
is not so useful.
This commit will changes those rules to always display the input. If
someone doesn't want the input to show, they can always set a name for
the rule.
I identified a pattern among rules that create results with adjacent
results, so I created a method that abstracts that. I did have to
compromise with the DateTimeDiff, having to escape the input instead of
using the name itself, but that seems like a good trade-off.
I've also renamed "Subsequent" to "Adjacent" because it sounded better.
This is the second time I've renamed this concept, and I hope it will be
the last.
The "Consecutive" rule is now renamed to "Circuit" to better reflect its
behavior of stopping at the first failure. I also favour this name
because it's much shorter.
This base class could also be used for other aggregate operations on
arrays, e.g. a sum. (It can't be used for `Length` though, as we would
not be able to validate a length of 0.).
This follows the same pattern as the `Length` rule.
I've also removed the separate named and standard templates from these
rules. I didn't see a good way to implement these in the new pattern,
and also felt the language of the old standard template was somewhat
difficult to read anyway.
To make PHPStan recognize methods when we call Validator with static and
non-static rule names, I added a few methods from `Validator` to the
`ChainedValidator` interface[1]. However, this didn't work so well
because there could have been more methods from `Validator`.
This commit will rename the mixins to better names, but it will also
make the `Chain` (old `ChainedValidator` to have a `@mixin` on itself of
the `Validator` class.
[1]: a974c0c834
Because of how PHP works, when we instantiate an Exception object, the
`file` and `line` properties are the file and line where we created the
object. That's a desirable behaviour, but there's no value for a user to
know that we created an instance of `ValidationException` in the
`Validator` class.
This commit will overwrite the file and line in the
`ValidationException` to where the method `assert()` was called.
Note that when running `check()` it will still point to `Validator`, but
I decided not to change it, as the method `check()` got deprecated.
Since I updated the validation engine[1], it became possible to create
results with subsequents[2]. This commit changes the "Length", allowing
it to create a result with a subsequent only when it's possible. That
will improve the clarity of the error messages.
[1]: 238f2d506a
[2]: 52e628fc6f
Currently, the Size rule does multiple things, yet it's limited. Because
it does many things, it's also confusing. Turning the Size rule into a
transformation allows for way more flexibility and clarity.
The syntax becomes more verbose, but the rule becomes more reusable.
Although I love PHPT files, and I've done my fair share of making it
easier to write them in this library, they're very slow, and running
them has become a hindrance.
I've been fidgeting with the idea of using Pest for a while, and I think
it's the right tool for the job. I had to create a couple of functions
to make it easier to run those tests, and now they're working really
alright.
I migrated all the PHPT files into Pest files -- I automated most of the
work with a little script using "nikic/php-parser"; this commit should
contain all the previous PHPT tests as Pest tests.
The previous integration tests would take sixteen seconds, and the Pest
tests take less than a second.
With this change, any rule can be used as a PHP attribute. I have wanted
to implement this feature for a while, as it allows you to bind the
validation to a specific property and just validate the object
afterwards.
In some cases, "DateTimeImmutable" will throw an exception because it
cannot parse the date. In those cases, we shouldn't throw an exception,
but instead return a specific result that tells what happened.
The way we display messages could have been better, and it took me a
while to realise that to make it better, I would need to handle the
siblings of a result before deciding whether we should render it.
Another issue was that rules like Key and Property had to create a
"dumb" parent just so we would display the messages correctly, and in
some cases, that wasn't even enough.
This commit introduces quite a few changes to how the library works,
making the messages much more straightforward.
With the "exceptionAll()" function, we can then have the single message,
the full message, and the messages as an array. That makes it harder to
get those bugs back.
There are several cases in which we need to bind the name and template
of a rule to another. We need to do that because results need
information from rules to be created, and because results come from
rules, in some cases, it's not ideal (or possible) to change the
information after the result is created.
There are a few use cases in which you would like to have a custom
exception but, at the same time, reuse the message or exception that
validation might give you.
This commit creates a new feature that allows users to define a callable
that will generate an exception when it fails.
