Validation rules documentation feedback

I love the cake validation module for how simple and straightforward it is.

I want to give feedback on the documentation for the rules, which I think could gain in clarity.

For instance, it seems that almost every rule that is not allowEmpty*() automatically sets a rule that the field cannot be null. I would have liked to see that information in the PHPDocs of the rules or mentioned clearly under the chapter “allowing empty fields” or even better in an own chapter on how null values and empty strings are handled per default among the other validation rules.
Especially after reading this in the requirePresence() documentation.

By default, true is used. Key presence is checked by using array_key_exists() so that null values will count as present.

But the rule will still have the effect that null adds an error. I was very surprised of this behaviour in the beginning. Technically the documentation is not wrong, and I understand it now, but I find it misleading when starting to work with this library.

Or allowEmptyString not only allows a field to be an empty string like the PHPDoc and documentation mention but also null and I don’t know what other values considered as “empty” that are allowed with this rule. I don’t know about 0, "0", false.
If this was written down somewhere, it would have saved a lot of time.

And for a lot of fields, more details on how the rule behaves, especially in edge cases, would be so helpful.
The email() rule has the following PHPDoc “Add an email validation rule to a field.”. This doesn’t tell me what the rule does if the string is empty, for instance.
When writing those rules, I need to be absolutely certain what values will create errors or not and if I need notEmptyString() or if I can omit it.

Same goes for the notBlank() rule. PHPDoc says “Add a notBlank rule to a field.” but what does “notBlank” exactly mean?

LLMs are quite confused with how the validation rules work and often give me wrong answers.
If I ask GPT-4 “how can I allow null in the cakephp validation library but disallow empty string” I get the following answer:

To allow null values in the CakePHP validation library, you can use the allowEmptyString() method. However, if you want to disallow empty strings, you can use the notBlank() method instead

When I ask “is null is considered empty” because I doubted that notBlank() would allow null while disallowing empty strings it doubles down.

In the context of the CakePHP validation library, null is not considered empty .
->notBlank() method is used to ensure that the input field is not empty. It returns false if the input field is empty, and true otherwise.
On the other hand, null is a value that represents the absence of a value.
Therefore, if you want to allow null values in the input field, you can use ->allowEmptyString() method with the third parameter set to false. This will allow null values but disallow empty strings. Then, you can use ->notBlank() method to ensure that the input field is not empty

When verified this with the GitHub Copilot chat and asked “can i use notblank and allowEmptyString to allow only null values but not empty strings” it responded:

Yes, you can use notBlank and allowEmptyString together to allow only null values but not empty strings. The allowEmptyString method will allow null values, and the notBlank method will disallow empty strings. Here is how you can do it:
$validator->allowEmptyString('first_name')->notBlank('first_name', __('Field is required'));
In this example, allowEmptyString(‘first_name’) allows the first_name field to be null or an empty string. Then notBlank(‘first_name’, __(‘Field is required’)) ensures that if a value is provided for first_name, it cannot be an empty string. So, the net effect is that first_name can be null but not an empty string.

Obviously this is wrong on many levels and I think the fact that the AI doesn’t get it and I can’t find this information in the documentation is quite telling that there is room for a lot of improvement.

That being said, I want to express profound gratitude for creating and maintaining this great tool. You all are amazing.