Move "Custom rules" documentation

Signed-off-by: Henrique Moody <henriquemoody@gmail.com>
This commit is contained in:
Henrique Moody 2019-05-22 20:51:38 +02:00
parent fbf82dc975
commit 7be7f0f58c
No known key found for this signature in database
GPG key ID: 221E9281655813A6
2 changed files with 72 additions and 74 deletions

72
docs/custom-rules.md Normal file
View file

@ -0,0 +1,72 @@
# Custom rules
You can also create and use your own rules. To do this, you will need to create
a rule and an exception to go with the rule.
To create a rule, you need to create a class that extends the AbstractRule class
and is within the Rules `namespace`. When the rule is called the logic inside the
validate method will be executed. Here's how the class should look:
```php
namespace My\Validation\Rules;
use Respect\Validation\Rules\AbstractRule;
final class Something extends AbstractRule
{
public function validate($input): bool
{
// Do something here with the $input and return a boolean value
}
}
```
Each rule must have an Exception to go with it. Exceptions should be named
with the name of the rule followed by the word Exception. The process of creating
an Exception is similar to creating a rule but there are no methods in the
Exception class. Instead, you create one static property that includes an
array with the information below:
```php
namespace My\Validation\Exceptions;
use Respect\Validation\Exceptions\ValidationException;
final class SomethingException extends ValidationException
{
protected $defaultTemplates = [
self::MODE_DEFAULT => [
self::STANDARD => 'Validation message if Something fails validation.',
],
self::MODE_NEGATIVE => [
self::STANDARD => 'Validation message if the negative of Something is called and fails validation.',
],
];
}
```
So in the end, the folder structure for your Rules and Exceptions should look
something like the structure below. Note that the folders (and namespaces) are
plural but the actual Rules and Exceptions are singular.
```
My
+-- Validation
+-- Exceptions
+-- SomethingException.php
+-- Rules
+-- Something.php
```
All classes in Validation are created by the `Factory` class. If you want
Validation to execute your rule (or rules) in the chain, you must overwrite the
default `Factory`.
```php
Factory::setDefaultInstance(
(new Factory())
->withRuleNamespace('My\\Validation\\Rules')
->withExceptionNamespace('My\\Validation\\Exceptions')
);
v::something(); // Try to load "My\Validation\Rules\Something" if any
```

View file

@ -266,80 +266,6 @@ Factory::setDefaultInstance(
);
```
## Custom rules
You can also create and use your own rules. To do this, you will need to create
a rule and an exception to go with the rule.
To create a rule, you need to create a class that extends the AbstractRule class
and is within the Rules `namespace`. When the rule is called the logic inside the
validate method will be executed. Here's how the class should look:
```php
namespace My\Validation\Rules;
use Respect\Validation\Rules\AbstractRule;
class MyRule extends AbstractRule
{
public function validate($input): bool
{
// Do something here with the $input and return a boolean value
}
}
```
Each rule must have an Exception to go with it. Exceptions should be named
with the name of the rule followed by the word Exception. The process of creating
an Exception is similar to creating a rule but there are no methods in the
Exception class. Instead, you create one static property that includes an
array with the information below:
```php
namespace My\Validation\Exceptions;
use \Respect\Validation\Exceptions\ValidationException;
class MyRuleException extends ValidationException
{
protected $defaultTemplates = [
self::MODE_DEFAULT => [
self::STANDARD => 'Validation message if MyRule fails validation.',
],
self::MODE_NEGATIVE => [
self::STANDARD => 'Validation message if the negative of MyRule is called and fails validation.',
],
];
}
```
So in the end, the folder structure for your Rules and Exceptions should look
something like the structure below. Note that the folders (and namespaces) are
plural but the actual Rules and Exceptions are singular.
```
My
+-- Validation
+-- Exceptions
+-- MyRuleException.php
+-- Rules
+-- MyRule.php
```
All classes in Validation are created by the `Factory` class. If you want
Validation to execute your rule (or rules) in the chain, you must overwrite the
default `Factory`.
```php
Factory::setDefaultInstance(
(new Factory())
->withRuleNamespace('My\\Validation\\Rules')
->withExceptionNamespace('My\\Validation\\Exceptions')
);
v::myRule(); // Try to load "My\Validation\Rules\MyRule" if any
v::alnum(); // Try to use "My\Validation\Rules\Alnum" if any, or else "Respect\Validation\Rules\Alnum"
```
## Validator name
On `v::attribute()` and `v::key()`, `{{name}}` is the attribute/key name. For others,