behance / nbd.php-validation
NBD.php Validation Component
Installs: 39 703
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 32
Forks: 11
Open Issues: 3
Requires
- php: ^7.0
Requires (Dev)
- phpunit/phpunit: ~6
README
NBD.php - Validation Component
Provides easy to use rules for checking various data types. Rules can be used in isolation, or chained together for a form-like validation interface.
Usage
Quickly validate a single data point
use Behance\NBD\Validation\Rules\IntegerRule;
$rule = new IntegerRule();
$valid = $rule->isValid( 123 ); // true
$valid = $rule->isValid( 'abc' ); // false
Validate a complex key-value array of "caged" data, like an HTML form
use Behance\NBD\Validation\Services\ValidatorService;
$validator = new ValidatorService();
// Define a series of rules: field key, field name, and a pipe-separated sequence of validator rules (from list below)
$validator->setRule( 'email', 'E-Mail', 'required|email' )
->setRule( 'first_name', 'First Name', 'required|alpha' )
->setRule( 'last_name', 'Last Name', 'required|alpha' )
->setRule( 'middle_i', 'Middle Initial', 'alpha|nullable|maxLength[1]' );
// Insert data to be validated
$validator->setCageData( $_POST );
// Obtain a single result for whether this data set passes the defined rules
$valid = $validator->run();
if ( !$valid ) {
// Loop through the failing fields
$errors = $validator->getAllFieldErrorMessages();
foreach ( $errors as $field => $message ) {
// ...
}
// Retrieves an error message string for all failed fields
$error_message = $validator->getAllFieldErrorMessagesString();
// Retrieves the unrendered error templates for all failed fields
$error_message = $validator->getAllFieldErrorTemplates();
// Retrieves the context for a given field error
$error_context = $validator->getFieldErrorContext( $field );
// Just retrieve the error message for email field
$email_message = $validator->getFieldErrorMessage( 'email' );
// Just retrieve the field keys that failed
$error_keys = $validator->getFailedFields();
} // if !valid
else {
// As a convenience, valid data points are available as magic properties
$email = $validator->email;
$first_name = $validator->first_name;
$last_name = $validator->last_name;
// You can check if a magic property exists using isset() whether or not it has passed validation.
$has_middle = isset( $validator->middle_i );
// Or, retrieve valid fields as a key-value array
$fields = $validator->getValidData(); // ex. [ 'email' => xxx, ... ], will discard unvalidated/failed fields
// Triple check that a field is valid
$email_valid = $validator->isFailed( 'email' ); // false
$field_name = $validator->getFieldName( $key ); // E-Mail
} // else (valid)
Available 'simple' validator rules (and growing):
- alpha
- alphaNumeric
- array
- decimal
- float
- hexColor
- postitiveInteger
- integer
- json
- notEmpty
- phone
- string
- url
- nestedArray
Available parameterized validator rules
Parameters are defined comma-separated inside brackets after rule:
Rule | Usage | Params | Explanation |
---|---|---|---|
matches | matches[target] | 1 | does the input match the value from the parameter with key 'target' |
minLength | minLength[5] | 1 | is string input length >=5 characters (defaults UTF-8, not byte count) |
maxLength | maxLength[5] | 1 | is string input length <=5 characters (defaults UTF-8, not byte count) |
instanceOf | instanceOf[stdClass] | 1 | is input an object and of type 'stdClass' |
range | range[1,10] | 2 | is input between 1 and 10 (inclusive) |
stringContains | stringContains[haystack] | 1 | is input a string and a needle for 'haystack' |
callback | callback[User,isUniqueEmail] | 2 | calls User::isUniqueEmail( $input ), interprets results as a boolean |
containedIn | containedIn[abc,def,ghi] | 1+ | input is in array of parameters (variable length) |
Special parameterized rules:
Rule | Usage | Params | Explanation |
---|---|---|---|
filter | filter[trim,md5] | 1+ | applies transformation of input, evaluating arguments left to right, transformation is seen by subsequent rules and subsequent retrieval. Parameter can be any single-parameter defined function that returns a transformed result. For example, using `filter[trim,md5]` will trim(), then md5() input, which would be coded as md5( trim( $input ) ). Placement of filter within validation rule is significant, as entire validation rule is also evaluated left to right. (e.g: calling `filter[trim]` before `notEmpty` will trim the input before checking if not empty). |
Other Special rules:
Rule | Explanation |
---|---|
required | The required rule checks if a field was passed into the validator. It does *not* validate the fields value and if it is empty or not. |
nullable | The nullable rule allows empty data to be passed to simulate clearing out a fields data. It accepts an empty string or `NULL` as valid input. |
Examples
Case | Valid |
---|---|
required nullable, where key doesn’t exist | false |
required nullable, where key exists but value is set to empty string/null | true |
required nullable, where key is truth-y | true |
optional nullable, where key doesn’t exist | true |
optional nullable, where key exists but value is set to empty string/null | true |
optional nullable, where key is truth-y | true |
- "valid" cases still depend on the rest of the rule set
- special rules cannot be used exclusive together or by themselves, they must be accompanied by other rules.
Add custom named validators quickly and easily:
use Behance\NBD\Validation\Services\ValidatorService;
$validator = new ValidatorService();
$rules = $validator->getRulesProvider();
// Creates a rule that can be used independently, or as part of the validator service
$regex_rule = $rules->setRegexRule( 'myNewRegexRule', '/^abcdefg$/' );
$valid = $regex_rule->isValid( 'abcdefg' ); // true
// Create a callback rule based on a boolean-returning closure, can also be used in both places
$closure = ( function( $data ) {
return $data == 'hello';
} );
$callback_rule = $rules->setCallbackRule( 'hello', $closure );
$callback_rule->isValid( 'hello' ); // true
#####Recursive Rules
The nestedArray
rule takes an additional 4th parameter, which is an array of rules
use Behance\NBD\Validation\Services\ValidatorService;
$validator = new ValidatorService();
$validator->setRules( [
[ 'email', 'E-Mail', 'required|email' ],
[ 'name', 'Name', 'nestedArray',
[
[ 'first_name', 'First Name', 'required|alpha' ],
[ 'last_name', 'Last Name', 'required|alpha' ],
[ 'middle_i', 'Middle Initial', 'alpha|nullable|maxLength[10]' ]
]
]
] );
also can set using setNestedRule:
$validator->setNestedRule( [ 'name', 'Name', 'nestedArray',
[
[ 'first_name', 'First Name', 'required|alpha' ],
[ 'last_name', 'Last Name', 'required|alpha' ],
[ 'middle_i', 'Middle Initial', 'alpha|nullable|maxLength[10]' ]
]
] );
$validator->runStrict();
$validated_data = $validator->getValidatedData();
$email = $validated_data['email'];
$first_name = $validated_data['name']['first_name'];
$last_name = $validated_data['name']['last_name'];
$middle_i = $validated_data['name']['middle_i'];