deblan-mirror/respect-validation
deblan-mirror/respect-validation
1
0
Fork 0
mirror of https://github.com/Respect/Validation.git synced 2024-06-06 07:42:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update "CONTRIBUTING.md" file

Browse source
This commit is contained in:
Henrique Moody 2015-10-18 20:26:33 -02:00
parent 954c0ca133
commit 477b1458bf
1 changed files with 102 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

134
CONTRIBUTING.md
View file

@ -1,8 +1,7 @@
# Contributing
Contributions to Respect\Validation are always welcome. You make our lives
easier by sending us your contributions through
[GitHub pull requests](http://help.github.com/pull-requests).
easier by sending us your contributions through [pull requests][].
Pull requests for bug fixes must be based on the current stable branch whereas
pull requests for new features must be based on `master`.
@ -11,14 +10,13 @@ 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.
Please see the [project documentation](http://respect.github.io/Validation)
before proceeding. You should also know about [PHP-FIG](http://www.php-fig.org)'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 `IntVal` to begin.
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.
Before writing anything, make sure there is no validator that already does what
you need. Also, it would be awesome if you
[open an issue](http://github.com/Respect/Validation/issues) before starting,
you need. Also, it would be awesome if you [open an issue][] before starting,
so if anyone has the same idea the guy will see that you're already doing that.
## Adding a new validator
@ -27,12 +25,12 @@ A common validator (rule) on Respect\Validation is composed of three classes:
* `library/Rules/YourRuleName.php`: the rule itself
* `library/Exceptions/YourRuleNameException.php`: the exception thrown by the rule
* `tests/Rules/YourRuleNameTest.php`: tests for the rule
* `tests/unit/Rules/YourRuleNameTest.php`: tests for the rule
Classes are pretty straightforward. In the sample below, we're going to create a
validator that validates if a string is equal "Hello World".
## Samples
### Creating the rule
The rule itself needs to implement the `Validatable` interface.
Also, it is convenient to extend the `AbstractRule`.
@ -43,6 +41,17 @@ If your validator class is `HelloWorld`, it will be available as `v::helloWorld(
and will natively have support for chaining and everything else.
```php
<?php
/*
* This file is part of Respect/Validation.
*
* (c) Alexandre Gomes Gaigalas <alexandre@gaigalas.net>
*
* For the full copyright and license information, please view the "LICENSE.md"
* file that was distributed with this source code.
*/
namespace Respect\Validation\Rules;
class HelloWorld extends AbstractRule
@ -54,12 +63,28 @@ class HelloWorld extends AbstractRule
}
```
Docblocks with `@param`, `@return`, `{@inheritdoc}`, `@author` and other
annotations for classes and methods are encouraged but not required.
### Creating the rule exception
Just that and we're done with the rule code. The Exception requires you to
declare messages used by `assert()` and `check()`. Messages are declared in
affirmative and negative moods, so if anyone calls `v::not(v::helloWorld())` the
library will show the appropriate message.
```php
<?php
/*
* This file is part of Respect/Validation.
*
* (c) Alexandre Gomes Gaigalas <alexandre@gaigalas.net>
*
* For the full copyright and license information, please view the "LICENSE.md"
* file that was distributed with this source code.
*/
namespace Respect\Validation\Exceptions;
class HelloWorldException extends ValidationException
@ -75,46 +100,80 @@ class HelloWorldException extends ValidationException
}
```
Finally, we need to test if everything is running smooth:
### 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
`PHPUnit_Framework_TestCase` if you want or you need it's necessary.
The `RuleTestCase` extends PHPUnit's `PHPUnit_Framework_TestCase` class, so you
are able to use any method of them. By extending `RuleTestCase` you should
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`
```php
<?php
/*
* This file is part of Respect/Validation.
*
* (c) Alexandre Gomes Gaigalas <alexandre@gaigalas.net>
*
* For the full copyright and license information, please view the "LICENSE.md"
* file that was distributed with this source code.
*/
namespace Respect\Validation\Rules;
class HelloWorldTest extends \PHPUnit_Framework_TestCase
/**
* @group rule
* @covers Respect\Validation\Rules\HelloWorld
*/
class HelloWorldTest extends RuleTestCase
{
public function testShouldValidateAValidHelloWorld()
public function providerForValidInput()
{
$rule = new HelloWorld();
$this->assertTrue($rule->validate('Hello World'));
return [
[$rule, 'Hello World'],
];
}
public function testNotValidateAnInvalidHelloWorld()
public function providerForInvalidInput()
{
$rule = new HelloWorld();
$this->assertFalse($rule->validate('Hello Moon'));
}
/**
* @expectedException Respect\Validation\Exceptions\HelloWorldException
* @expectedExceptionMessage "Hello Mars" must be a Hello World
*/
public function testShouldThowsTheRightExceptionWhenChecking()
{
$rule = new HelloWorld();
$rule->check('Hello Mars');
return [
[$rule, 'Not a hello'],
[$rule, 'Hello darkness, my old friend'],
[$rule, 'Hello is it me you\'re looking for?'],
];
}
}
```
PS.: We strongly recommend you use [Data Providers](https://phpunit.de/manual/current/en/writing-tests-for-phpunit.html#writing-tests-for-phpunit.data-providers).
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
You rule will be accepted only with these 3 files (rule, exception and unit test),
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.
As I already said, none of them are required but you will help us a lot.
## Documentation
Our docs at http://respect.github.io/Validation are generated from our Markdown
files using [Couscous](http://couscous.io/). Add your brand new rule there and
files using [Couscous][]. Add your brand new rule there and
everything will be updated as soon as possible.
## Running Tests
@ -142,11 +201,10 @@ and changing it according to your needs.
## Coding style and standards
We follow the [PSR-2](http://www.php-fig.org/psr/psr-2/) coding style and
[PSR-4](http://www.php-fig.org/psr/psr-4/) autoloading standard.
We follow the [PSR-2][] coding style and [PSR-4][] autoloading standard.
There are some preferences regarding code style which you can easily adhere to
by using [php-cs-fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer).
by using [php-cs-fixer][].
This will format all PHP files consistently using the preferences of this
project.
@ -163,3 +221,15 @@ See also:
- [License](LICENSE.md)
- [Validators](docs/VALIDATORS.md)
- [Changelog](CHANGELOG.md)
[ArrayType]: https://github.com/Respect/Validation/commit/f08a1fa
[Couscous]: http://couscous.io/ "Couscous"
[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-cs-fixer]: https://github.com/FriendsOfPHP/PHP-CS-Fixer "PHP Coding Standard Fixer"
[PHP-FIG]: http://www.php-fig.org "PHP Framework Interop Group"
[project documentation]: http://respect.github.io/Validation "Respect\Validation documentation"
[PSR-2]: http://www.php-fig.org/psr/psr-2 "PHP Standard Recommendation: Coding Style Guide"
[PSR-4]: http://www.php-fig.org/psr/psr-4 "PHP Standard Recommendation: Autoloader"
[pull requests]: http://help.github.com/pull-requests "GitHub pull requests"