Editor PHP 2.3.2

Validate
in package

Validation methods for DataTables Editor fields.

These methods will typically be applied through the Field::validator() method and thus the arguments to be passed will be automatically resolved by Editor.

The validation methods in this class all take three parameters:

  1. Data to be validated
  2. Full data from the form (this can be used with a custom validation method for dependent validation).
  3. Validation configuration options.

When using the Validate class functions with the Field::validator() method, the second parameter passed into Field::validator() is given to the validation functions here as the third parameter. The first and second parameters are automatically resolved by the Field class.

The validation configuration options is an array of options that can be used to customise the validation - for example defining a date format for date validation. Each validation method has the option of defining its own validation options, but all validation methods provide four common options:

  • {boolean} optional - Require the field to be submitted (false) or not (true - default). When set to true the field does not need to be included in the list of parameters sent by the client - if set to false then it must be included. This option can be be particularly used in Editor as Editor will not set a value for fields which have not been submitted - giving the ability to submit just a partial list of options.
  • {boolean} empty - Allow a field to be empty, i.e. a zero length string - '' (true - default) or require it to be non-zero length (false).
  • {boolean} required - Short-cut for optional=false and empty=false. Note that if this option is set the optional and empty parameters are automatically set and cannot be overridden by passing in different values.
  • {string} message - Error message shown should validation fail. This provides complete control over the message shown to the end user, including internationalisation (i.e. to provide a translation that is not in the English language).
Tags
example 
  // Ensure that a non-empty value is given for a field
  (new Field( 'engine' ))->validator( Validate::required() )
example 
  // Don't require a field to be submitted, but if it is submitted, it
  // must be non-empty
  (new Field( 'reg_date' ))->validator( Validate::notEmpty() )
example 
  // Date validation
  (new Field( 'reg_date' ))->validator( Validate::dateFormat( 'D, d M y' ) )
example 
  // Date validation with a custom error message
  (new Field( 'reg_date' ))->validator( Validate::dateFormat( 'D, d M y',
      (new ValidateOptions())
          ->message( 'Invalid date' )
  ) )
example 
  // Require a non-empty e-mail address
  (new Field( 'reg_date' ))->validator( Validate::email( (new ValidateOptions())
    ->empty( false )
  ) )
example 
  // Custom validation - closure
  (new Field( 'engine' ))->validator( function($val, $data, $opts) {
     if ( ! preg_match( '/^1/', $val ) ) {
       return "Value <b>must</b> start with a 1";
     }
     return true;
  } )

Table of Contents

Methods

basic()  : string|true
Basic validation - this is used to perform the validation provided by the validation options only. If the validation options pass (e.g. `required`, `empty` and `optional`) then the validation will pass regardless of the actual value.
boolean()  : string|true
Validate an input as a boolean value.
dateFormat()  : string|true
Check that a valid date input is given.
dbValues()  : string|true
Check that the given value is a value that is available in a database - i.e. a join primary key. This will attempt to automatically use the table name and value column from the field's `options` method (under the assumption that it will typically be used with a joined field), but the table and field can also be specified via the options.
email()  : string|true
Validate an input as an e-mail address.
fileExtensions()  : mixed
fileSize()  : mixed
ip()  : string|true
Validate as an IP address.
maxLen()  : string|true
Validate a string does not exceed a maximum length.
maxNum()  : string|true
Check for a numeric input and that it is less than a given value.
minLen()  : string|true
Validate a string has a minimum length.
minMaxLen()  : string|true
Require a string with a certain minimum or maximum number of characters.
minMaxNum()  : string|true
Check for a numeric input and that it is both greater and smaller than given numbers.
minNum()  : string|true
Check for a numeric input and that it is greater than a given value.
mjoinMaxCount()  : mixed
mjoinMinCount()  : mixed
none()  : callable
No validation - all inputs are valid.
noTags()  : string|true
Check if there are any tags in the submitted value.
notEmpty()  : callable
Optional field, but if given there must be a non-empty value.
numeric()  : string|true
Check that any input is numeric.
required()  : string|true
Required field - there must be a value and it must be a non-empty value.
unique()  : string|true
Check that the given value is unique in the database.
url()  : string|true
Validate as an URL address.
values()  : string|true
Confirm that the value submitted is in a list of allowable values.
xss()  : string|true
Check if string could contain an XSS attack string.

Methods

basic()

Basic validation - this is used to perform the validation provided by the validation options only. If the validation options pass (e.g. `required`, `empty` and `optional`) then the validation will pass regardless of the actual value.

public static basic([mixed $cfg = null ]) : string|true

Note that there are two helper short-cut methods that provide the same function as this method, but are slightly shorter:

// Required:
Validate::required()

// is the same as
Validate::basic( $val, $data, [
  "required" => true
];

// Optional, but not empty if given:
Validate::notEmpty()

// is the same as
Validate::basic( $val, $data, [
  "empty" => false
];
Parameters
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

array $opts Validation options. No additional options are available or required for this validation method.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

boolean()

Validate an input as a boolean value.

public static boolean([mixed $cfg = null ]) : string|true
Parameters
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

array $opts Validation options. No additional options are available or required for this validation method.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

dateFormat()

Check that a valid date input is given.

public static dateFormat(mixed $format[, mixed $cfg = null ]) : string|true
Parameters
$format : mixed
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

array|string $opts If given as a string, then $opts is the date format to check the validity of. If given as an array, then the date format is in the 'format' parameter, and the return error message in the 'message' parameter.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

dbValues()

Check that the given value is a value that is available in a database - i.e. a join primary key. This will attempt to automatically use the table name and value column from the field's `options` method (under the assumption that it will typically be used with a joined field), but the table and field can also be specified via the options.

public static dbValues([mixed $cfg = null ][, mixed $column = null ][, mixed $table = null ][, mixed $db = null ][, mixed $values = [] ]) : string|true
Parameters
$cfg : mixed = null
$column : mixed = null
$table : mixed = null
$db : mixed = null
$values : mixed = []
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. The additional options of db - database connection object, table - database table to use and column - the column to check this value against as value, are also available. These options are not required and if not given are automatically derived from the Editor and Field instances.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

email()

Validate an input as an e-mail address.

public static email([mixed $cfg = null ]) : string|true
Parameters
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

array $opts Validation options. No additional options are available or required for this validation method.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

fileExtensions()

public static fileExtensions(mixed $extensions[, mixed $msg = 'This file type cannot be uploaded.' ]) : mixed
Parameters
$extensions : mixed
$msg : mixed = 'This file type cannot be uploaded.'

fileSize()

public static fileSize(mixed $size[, mixed $msg = 'Uploaded file is too large.' ]) : mixed
Parameters
$size : mixed
$msg : mixed = 'Uploaded file is too large.'

ip()

Validate as an IP address.

public static ip([mixed $cfg = null ]) : string|true
Parameters
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

array $opts Validation options. No additional options are available or required for this validation method.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

maxLen()

Validate a string does not exceed a maximum length.

public static maxLen(mixed $max[, mixed $cfg = null ]) : string|true
Parameters
$max : mixed
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. The additional option of max is available for this method to indicate the maximum string length. If only the default validation options are required, this parameter can be given as an integer value, which will be used as the maximum string length.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

maxNum()

Check for a numeric input and that it is less than a given value.

public static maxNum(mixed $max[, mixed $decimal = '.' ][, mixed $cfg = null ]) : string|true
Parameters
$max : mixed
$decimal : mixed = '.'
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options.

  • max: indicate the maximum value. If only the default validation options are required, this parameter can be given as an integer value, which will be used as the maximum value.
  • decimal: is available to indicate what character should be used as the decimal
callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

minLen()

Validate a string has a minimum length.

public static minLen(mixed $min[, mixed $cfg = null ]) : string|true
Parameters
$min : mixed
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. The additional option of min is available for this method to indicate the minimum string length. If only the default validation options are required, this parameter can be given as an integer value, which will be used as the minimum string length.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

minMaxLen()

Require a string with a certain minimum or maximum number of characters.

public static minMaxLen(mixed $min, mixed $max[, mixed $cfg = null ]) : string|true
Parameters
$min : mixed
$max : mixed
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. The additional options of min and max are available for this method to indicate the minimum and maximum string lengths, respectively.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

minMaxNum()

Check for a numeric input and that it is both greater and smaller than given numbers.

public static minMaxNum(mixed $min, mixed $max[, mixed $decimal = '.' ][, mixed $cfg = null ]) : string|true
Parameters
$min : mixed
$max : mixed
$decimal : mixed = '.'
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. Additional options:

  • min: indicate the minimum value.
  • max: indicate the maximum value.
  • decimal: is available to indicate what character should be used as the decimal
callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

minNum()

Check for a numeric input and that it is greater than a given value.

public static minNum(mixed $min[, mixed $decimal = '.' ][, mixed $cfg = null ]) : string|true
Parameters
$min : mixed
$decimal : mixed = '.'
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. Additional options:

  • min: indicate the minimum value. If only the default validation options are required, this parameter can be given as an integer value, which will be used as the minimum value.
  • decimal: is available to indicate what character should be used as the decimal separator (default '.').
callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

mjoinMaxCount()

public static mjoinMaxCount(mixed $count[, mixed $msg = 'Too many items.' ]) : mixed
Parameters
$count : mixed
$msg : mixed = 'Too many items.'

mjoinMinCount()

public static mjoinMinCount(mixed $count[, mixed $msg = 'Too few items.' ]) : mixed
Parameters
$count : mixed
$msg : mixed = 'Too few items.'

none()

No validation - all inputs are valid.

public static none() : callable
Return values
callable —

Validation function

noTags()

Check if there are any tags in the submitted value.

public static noTags([mixed $cfg = null ]) : string|true
Parameters
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. The additional options of db - database connection object, table - database table to use and column - the column to check this value against as value, are also available. These options are not required and if not given are automatically derived from the Editor and Field instances.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

notEmpty()

Optional field, but if given there must be a non-empty value.

public static notEmpty([ValidateOptions $cfg = null ]) : callable

This is a helper short-cut method which is the same as:

Validate::basic( $val, $data, [
  "empty" => false
];
Parameters
$cfg : ValidateOptions = null

Validation options

Return values
callable —

Validation function

numeric()

Check that any input is numeric.

public static numeric([mixed $decimal = '.' ][, mixed $cfg = null ]) : string|true
Parameters
$decimal : mixed = '.'
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

array $opts Validation options. Additional options:

  • decimal: is available to indicate what character should be used as the decimal
callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

required()

Required field - there must be a value and it must be a non-empty value.

public static required([mixed $cfg = null ]) : string|true

This is a helper short-cut method which is the same as:

Validate::basic( $val, $data, [
  "required" => true
];
Parameters
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

array $opts Validation options. No additional options are available or required for this validation method.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

unique()

Check that the given value is unique in the database.

public static unique([mixed $cfg = null ][, mixed $column = null ][, mixed $table = null ][, mixed $db = null ]) : string|true
Parameters
$cfg : mixed = null
$column : mixed = null
$table : mixed = null
$db : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. The additional options of db - database connection object, table - database table to use and column - the column to check this value against as value, are also available. These options are not required and if not given are automatically derived from the Editor and Field instances.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

url()

Validate as an URL address.

public static url([mixed $cfg = null ]) : string|true
Parameters
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

array $opts Validation options. No additional options are available or required for this validation method.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

values()

Confirm that the value submitted is in a list of allowable values.

public static values(mixed $values[, mixed $cfg = null ]) : string|true
Parameters
$values : mixed
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. The additional options of db - database connection object, table - database table to use and column - the column to check this value against as value, are also available. These options are not required and if not given are automatically derived from the Editor and Field instances.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.

xss()

Check if string could contain an XSS attack string.

public static xss([mixed $cfg = null ]) : string|true
Parameters
$cfg : mixed = null
Tags
callback-param

string $val The value to check for validity

callback-param

string[] $data The full data set submitted

callback-param

int|array $opts Validation options. The additional options of db - database connection object, table - database table to use and column - the column to check this value against as value, are also available. These options are not required and if not given are automatically derived from the Editor and Field instances.

callback-param

array $host Host information

Return values
string|true —

true if the value is valid, a string with an error message otherwise.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results