3.9 KiB
Respect\Validation - How to Contribute
This is a guide for anyone willing to contribute with Respect\Validation. Anyone can contribute!
Please see the project documentation
before proceeding. You should also know about PSR-0 and basic unit testing, but
I'm sure you can learn that just by looking at other rules. Pick the simple ones
like Int
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 before starting, so if anyone has the same idea the guy will see that you're already doing that.
Adding a new Validator
A common validator on Respect is composed of three classes:
- library/Respect/Validation/Rules/YourRuleName.php - The rule itself
- library/Respect/Validation/Exceptions/YourRuleNameException.php - The exception thrown by the rule
- tests/library/Respect/Validation/Exceptions/YourRuleNameTest.php - Tests for the validator
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
The rule itself needs to implement the Validatable interface. Also, it is convenient
to extend the AbstractRule. Doing that, you'll only need to declare one method:
validate($input)
. This method must return true or false.
namespace Respect\Validation\Rules;
use Respect\Validation\Validatable;
class HelloWorld extends AbstractRule implements Validatable
{
public function validate($input)
{
return $input === 'Hello World';
}
}
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())
Respect will show
the appropriate message.
namespace Respect\Validation\Exceptions;
class HelloWorldException extends ValidationException
{
public static $defaultTemplates = array(
self::MODE_DEFAULT => array(
self::STANDARD => '{{name}} must be a Hello World',
),
self::MODE_NEGATIVE => array(
self::STANDARD => '{{name}} must not be a Hello World',
)
);
}
Finally, we need to test if everything is running smooth:
namespace Respect\Validation\Rules;
class HelloWorldTest extends \PHPUnit_Framework_TestCase
{
protected $validator;
protected function setUp()
{
$this->validator = new HelloWorld;
}
public function testOk($input)
{
$this->assertTrue($this->validator->validate('Hello World'));
$this->assertTrue($this->validator->check('Hello World'));
$this->assertTrue($this->validator->assert('Hello World'));
}
/** @expectedException Respect\Validation\Exceptions\HelloWorldException */
public function testFailAssert($input)
{
$this->assertFalse($this->validator->validate('Lorem Ipsum'));
$this->assertFalse($this->validator->assert('Lorem Ipsum'));
}
/** @expectedException Respect\Validation\Exceptions\HelloWorldException */
public function testFailCheck($input)
{
$this->assertFalse($this->validator->validate('Lorem Ipsum'));
$this->assertFalse($this->validator->check('Lorem Ipsum'));
}
}
Documentation
Our docs at http://documentup.com/Respect/Validation are generated by our README.md on the project root. Add your brand new rule there and everything will update automatically =)
If your validator class is HelloWorld
, it will be available as v::helloWorld()
and will natively have support for chaining and everything else.
Running Tests
Make sure you have PHPUnit installed. Instructions can be found on http://phpunit.de.
Then, go to the tests
folder on your terminal and type phpunit .
. No test should fail.
Sending your code to us
Please see http://help.github.com/pull-requests/.