2015-02-01 13:41:13 +01:00
|
|
|
# Contributing
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-02-01 13:41:13 +01:00
|
|
|
Contributions to Respect\Validation are always welcome. You make our lives
|
2015-10-19 00:26:33 +02:00
|
|
|
easier by sending us your contributions through [pull requests][].
|
2015-02-01 13:41:13 +01:00
|
|
|
|
2019-05-23 16:35:41 +02:00
|
|
|
Pull requests for bug fixes must be based on the oldest stable version's branch
|
|
|
|
whereas pull requests for new features must be based on the `master` branch.
|
2015-02-01 13:41:13 +01:00
|
|
|
|
|
|
|
Due to time constraints, we are not always able to respond as quickly as we
|
|
|
|
would like. Please do not take delays personal and feel free to remind us here,
|
|
|
|
on IRC, or on Gitter if you feel that we forgot to respond.
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-10-19 00:26:33 +02:00
|
|
|
Please see the [project documentation][] before proceeding. You should also know
|
|
|
|
about [PHP-FIG][]'s standards and basic unit testing, but we're sure you can
|
|
|
|
learn that just by looking at other rules. Pick the simple ones like `ArrayType`
|
|
|
|
to begin.
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-11-18 08:47:35 +01:00
|
|
|
Before writing anything, feature or bug fix:
|
|
|
|
- Check if there is already an issue related to it (opened or closed) and if
|
|
|
|
someone is already working on that;
|
|
|
|
- If there is not, [open an issue][] and notify everybody that you're going
|
|
|
|
to work on that;
|
|
|
|
- If there is, create a comment to notify everybody that you're going to
|
|
|
|
work on that.
|
|
|
|
- Make sure that what you need is not done yet
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-02-01 13:41:13 +01:00
|
|
|
## Adding a new validator
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-02-01 13:41:13 +01:00
|
|
|
A common validator (rule) on Respect\Validation is composed of three classes:
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-02-01 13:41:13 +01:00
|
|
|
* `library/Rules/YourRuleName.php`: the rule itself
|
2015-10-19 00:26:33 +02:00
|
|
|
* `tests/unit/Rules/YourRuleNameTest.php`: tests for the rule
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-11-18 08:47:35 +01:00
|
|
|
The classes are pretty straightforward. In the sample below, we're going to
|
|
|
|
create a validator that validates if a string is equal to "Hello World".
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2018-01-07 14:48:31 +01:00
|
|
|
- Classes should be `final` unless they are used in a different scope;
|
|
|
|
- Properties should be `private` unless they are used in a different scope;
|
|
|
|
- Classes should use strict typing;
|
2019-05-23 16:35:41 +02:00
|
|
|
- Some docblocks are required.
|
2018-01-07 14:48:31 +01:00
|
|
|
|
2015-10-19 00:26:33 +02:00
|
|
|
### Creating the rule
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-11-18 08:47:35 +01:00
|
|
|
The rule itself needs to implement the `Validatable` interface but, it is
|
2024-03-25 09:18:05 +01:00
|
|
|
convenient to just extend the `Simple` or `Standard` class.
|
2015-02-01 13:41:13 +01:00
|
|
|
Doing that, you'll only need to declare one method: `validate($input)`.
|
|
|
|
This method must return `true` or `false`.
|
|
|
|
|
|
|
|
If your validator class is `HelloWorld`, it will be available as `v::helloWorld()`
|
|
|
|
and will natively have support for chaining and everything else.
|
2015-01-02 22:00:09 +01:00
|
|
|
|
|
|
|
```php
|
2015-10-19 00:26:33 +02:00
|
|
|
<?php
|
|
|
|
|
|
|
|
/*
|
2023-02-17 05:13:51 +01:00
|
|
|
* Copyright (c) Alexandre Gomes Gaigalas <alganet@gmail.com>
|
|
|
|
* SPDX-License-Identifier: MIT
|
2015-10-19 00:26:33 +02:00
|
|
|
*/
|
|
|
|
|
2018-01-07 14:48:31 +01:00
|
|
|
declare(strict_types=1);
|
|
|
|
|
2015-01-02 22:00:09 +01:00
|
|
|
namespace Respect\Validation\Rules;
|
|
|
|
|
2024-02-06 02:00:27 +01:00
|
|
|
use Respect\Validation\Message\Template;
|
2024-03-25 09:18:05 +01:00
|
|
|
use Respect\Validation\Rules\Core\Simple;
|
2024-01-29 20:43:02 +01:00
|
|
|
|
|
|
|
#[Template(
|
|
|
|
'{{name}} must be a Hello World',
|
|
|
|
'{{name}} must not be a Hello World',
|
|
|
|
)]
|
2024-03-25 09:18:05 +01:00
|
|
|
final class HelloWorld extends Simple
|
2015-01-02 22:00:09 +01:00
|
|
|
{
|
2024-03-25 09:18:05 +01:00
|
|
|
protected function isValid(mixed $input): bool
|
2015-01-02 22:00:09 +01:00
|
|
|
{
|
|
|
|
return $input === 'Hello World';
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2015-10-19 00:26:33 +02:00
|
|
|
### Creating unit tests
|
|
|
|
|
|
|
|
Finally, we need to test if everything is running smooth. We have `RuleTestCase`
|
|
|
|
that allows us to make easier to test rules, but you fell free to use the
|
2017-11-04 11:21:40 +01:00
|
|
|
`PHPUnit\Framework\TestCase` if you want or you need it's necessary.
|
2015-10-19 00:26:33 +02:00
|
|
|
|
2017-11-04 11:21:40 +01:00
|
|
|
The `RuleTestCase` extends PHPUnit's `PHPUnit\Framework\TestCase` class, so you
|
2015-11-18 08:47:35 +01:00
|
|
|
are able to use any methods of it. By extending `RuleTestCase` you should
|
2015-10-19 00:26:33 +02:00
|
|
|
implement two methods that should return a [data provider][] with the rule as
|
|
|
|
first item of the arrays:
|
|
|
|
|
|
|
|
- `providerForValidInput`: Will test when `validate()` should return `true`
|
|
|
|
- `providerForInvalidInput`: Will test when `validate()` should return `false`
|
2015-01-02 22:00:09 +01:00
|
|
|
|
|
|
|
```php
|
2015-10-19 00:26:33 +02:00
|
|
|
<?php
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-10-19 00:26:33 +02:00
|
|
|
/*
|
2023-02-17 05:13:51 +01:00
|
|
|
* Copyright (c) Alexandre Gomes Gaigalas <alganet@gmail.com>
|
|
|
|
* SPDX-License-Identifier: MIT
|
2015-10-19 00:26:33 +02:00
|
|
|
*/
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2018-01-07 14:48:31 +01:00
|
|
|
declare(strict_types=1);
|
|
|
|
|
2015-10-19 00:26:33 +02:00
|
|
|
namespace Respect\Validation\Rules;
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2024-01-28 01:46:21 +01:00
|
|
|
use PHPUnit\Framework\Attributes\CoversClass;
|
|
|
|
use PHPUnit\Framework\Attributes\Group;
|
2018-01-07 14:48:31 +01:00
|
|
|
use Respect\Validation\Test\RuleTestCase;
|
|
|
|
|
2024-01-28 01:46:21 +01:00
|
|
|
#[Group('rule')]
|
|
|
|
#[CoversClass(HelloWorld::class)]
|
2018-01-07 14:48:31 +01:00
|
|
|
final class HelloWorldTest extends RuleTestCase
|
2015-10-19 00:26:33 +02:00
|
|
|
{
|
2024-02-04 19:14:53 +01:00
|
|
|
/** @return array<array{HelloWorld, mixed}> */
|
|
|
|
public static function providerForValidInput(): iterable
|
2015-01-02 22:00:09 +01:00
|
|
|
{
|
2024-02-04 19:14:53 +01:00
|
|
|
yield [new HelloWorld(), 'Hello World'];
|
2015-01-02 22:00:09 +01:00
|
|
|
}
|
|
|
|
|
2024-02-04 19:14:53 +01:00
|
|
|
/** @return array<array{HelloWorld, mixed}> */
|
|
|
|
public static function providerForInvalidInput(): iterable
|
2015-01-02 22:00:09 +01:00
|
|
|
{
|
2015-02-01 13:41:13 +01:00
|
|
|
$rule = new HelloWorld();
|
|
|
|
|
2024-02-04 19:14:53 +01:00
|
|
|
yield [$rule, 'Not a hello'];
|
|
|
|
yield [$rule, 'Hello darkness, my old friend'];
|
|
|
|
yield [$rule, 'Hello is it me you\'re looking for?'];
|
2015-01-02 22:00:09 +01:00
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2015-10-19 00:26:33 +02:00
|
|
|
If the constructor of your rule accepts arguments you may create specific tests
|
|
|
|
for it other than what is covered by `RuleTestCase`.
|
|
|
|
|
|
|
|
### Helping us a little bit more
|
|
|
|
|
2024-01-29 20:43:02 +01:00
|
|
|
You rule will be accepted only with these 3 files (rule and unit test),
|
2015-10-19 00:26:33 +02:00
|
|
|
but if you really want to help us, you can follow the example of [ArrayType][] by:
|
|
|
|
|
|
|
|
- Adding your new rule on the `Validator`'s class docblock;
|
|
|
|
- Writing a documentation for your new rule;
|
|
|
|
- Creating integration tests with PHPT.
|
|
|
|
|
2015-11-18 08:47:35 +01:00
|
|
|
As we already said, none of them are required but you will help us a lot.
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-02-01 13:41:13 +01:00
|
|
|
## Documentation
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2019-05-23 16:35:41 +02:00
|
|
|
Our docs at https://respect-validation.readthedocs.io are generated from our
|
|
|
|
Markdown files. Add your brand new rule and it should be soon available.
|
2015-01-02 22:00:09 +01:00
|
|
|
|
|
|
|
## Running Tests
|
|
|
|
|
2015-01-07 05:55:07 +01:00
|
|
|
After run `composer install` on the library's root directory you must run PHPUnit.
|
|
|
|
|
|
|
|
### Linux
|
|
|
|
|
|
|
|
You can test the project using the commands:
|
|
|
|
```sh
|
|
|
|
$ vendor/bin/phpunit
|
|
|
|
```
|
|
|
|
|
2015-10-19 14:12:55 +02:00
|
|
|
or
|
|
|
|
|
|
|
|
```sh
|
2019-05-23 16:35:41 +02:00
|
|
|
$ composer phpunit
|
2015-10-19 14:12:55 +02:00
|
|
|
```
|
|
|
|
|
2015-01-07 05:55:07 +01:00
|
|
|
### Windows
|
|
|
|
|
|
|
|
You can test the project using the commands:
|
|
|
|
```sh
|
2015-02-01 13:41:13 +01:00
|
|
|
> vendor\bin\phpunit
|
2015-01-07 05:55:07 +01:00
|
|
|
```
|
|
|
|
|
2015-10-19 14:12:55 +02:00
|
|
|
or
|
|
|
|
|
|
|
|
```sh
|
2019-05-23 16:35:41 +02:00
|
|
|
> composer phpunit
|
2015-10-19 14:12:55 +02:00
|
|
|
```
|
|
|
|
|
2015-01-07 05:55:07 +01:00
|
|
|
No test should fail.
|
2015-01-02 22:00:09 +01:00
|
|
|
|
2015-02-01 13:41:13 +01:00
|
|
|
You can tweak the PHPUnit's settings by copying `phpunit.xml.dist` to `phpunit.xml`
|
|
|
|
and changing it according to your needs.
|
2015-02-21 10:35:02 +01:00
|
|
|
|
2015-10-19 00:26:33 +02:00
|
|
|
[ArrayType]: https://github.com/Respect/Validation/commit/f08a1fa
|
|
|
|
[data provider]: https://phpunit.de/manual/current/en/writing-tests-for-phpunit.html#writing-tests-for-phpunit.data-providers "PHPUnit Data Providers"
|
|
|
|
[open an issue]: http://github.com/Respect/Validation/issues
|
|
|
|
[PHP-FIG]: http://www.php-fig.org "PHP Framework Interop Group"
|
2019-05-23 16:35:41 +02:00
|
|
|
[project documentation]: https://respect-validation.readthedocs.io/ "Respect\Validation documentation"
|
2015-10-19 00:26:33 +02:00
|
|
|
[pull requests]: http://help.github.com/pull-requests "GitHub pull requests"
|