behance/nbd.php-validation

This package is abandoned and no longer maintained. No replacement package was suggested.

NBD.php Validation Component

2.3.0 2018-05-15 22:16 UTC

README

Build Status Dependency Status

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
  • email
  • 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 ParamsExplanation
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:
RuleUsageParamsExplanation
filterfilter[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:
RuleExplanation
requiredThe 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.
nullableThe 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
CaseValid
required nullable, where key doesn’t existfalse
required nullable, where key exists but value is set to empty string/nulltrue
required nullable, where key is truth-ytrue
optional nullable, where key doesn’t existtrue
optional nullable, where key exists but value is set to empty string/nulltrue
optional nullable, where key is truth-ytrue
  • "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'];