PHP Class Gdn_Validation, vanilla

Show file Open project: vanilla/vanilla Class Usage Examples

Protected Properties

Property	Type	Description
$_FieldRules		An associative array of $FieldName => array($RuleName1, $RuleNameN) rules to be applied to fields. These are rules that have been explicitly called with {@link Gdn_Validation::ApplyRule()}.
$_ResetOnValidate		Whether or not to reset the validation results on validate.
$_Rules		The collection of validation rules in the format of $RuleName => $Rule. This list can be added to with $this->AddRule($RuleName, $Rule).
$_Schema		The schema being used to generate validation rules.
$_SchemaRules		An associative array of $FieldName => array($RuleName1, $RuleNameN) rules to be applied to fields. These are rules that come from the current schema that have been applied by {@link Gdn_Validation::ApplyRulesBySchema()}.
$_ValidationFields		An associative array of fieldname => value pairs that are being validated. In order for a field to become a part of this collection, it must either be present in the defined schema, or have a rule defined in $this->_FieldRules.
$_ValidationResults		An array of FieldName => Reason arrays that describe which fields failed validation and which functions/regex caused them to fail.

Public Methods

Method	Description
__construct ( Gdn_Schema \| array $Schema = false, $ResetOnValidate = false )	Class constructor. Optionally takes a schema definition to generate validation rules for.
addRule ( string $RuleName, string $Rule )	Adds to the rules collection ($this->_Rules).
addValidationResult ( string $FieldName, string $ErrorCode = '' )	Add a validation result (error) to the validation.
applyRule ( string $FieldName, mixed $RuleName, mixed $CustomError = '' )	Applies a $RuleName to a $FieldName. You can apply as many rules to a field as you like.
applySchema ( array $Schema )	Allows the explicit definition of a schema to use.
getSchemaRules ( ) : array	Get all of the rules as defined by the schema.
reset ( )	Reset the validation results to an empty array.
resetOnValidate ( ) : boolean	Whether or not the validation results etc should reset whenever {@link Validate()} is called.
results ( boolean $Reset = false ) : array	Returns the $this->_ValidationResults array. You must use this method because the array is read-only outside this object.
resultsArray ( ) : array	Get the validation results as an array of error messages.
resultsAsArray ( array $results ) : array	Expand the validation results into a single-dimension array.
resultsAsText ( array $results ) : string	Format an array of validation results as a string.
resultsText ( ) : string	Get the validation results as a string of text.
schemaValidationFields ( ) : array	Returns an array of field names that are in both $this->_ValidationFields AND $this->_Schema.
setResetOnValidate ( boolean $ResetOnValidate ) : Gdn_Validation	Set whether or not the validation results etc should reset whenever {@link Validate()} is called.
setSchema ( Gdn_Schema \| array $Schema ) : Gdn_Validation	Set the schema for this validation.
setSchemaProperty ( string $FieldName, string $PropertyName, mixed $Value )	Allows you to explicitly set a field property on $this->_Schema. Can be useful when adding rules to fields (ie. a maxlength property on a db's text field).
unapplyRule ( $FieldName, boolean $RuleName = false )	Remove a validation rule that was added with {@link Gdn_Validation::ApplyRule()}.
validate ( array $PostedFields, boolean $Insert = false ) : boolean	Examines the posted fields, defines $this->_ValidationFields, and enforces the $this->Rules collection on them.
validateRule ( mixed $Value, string $FieldName, string \| array $Rule, string $CustomError = false ) : boolean \| string	Execute a single validation rule and return its result.
validationFields ( ) : array	Returns the an array of fieldnames that are being validated.

Protected Methods

Method	Description
addValidationField ( string $FieldName, array $PostedFields )	Adds a fieldname to the $this->_ValidationFields collection.
applyRuleTo ( array &$Array, string $FieldName, string $RuleName, string $CustomError = '' )	Apply a rule to the given rules array.
applyRulesBySchema ( )	Examine the current schema and fill {@link Gdn_Validation::$_SchemaRules}.
defineValidationFields ( array $PostedFields, boolean $Insert = false ) : array	Fills $this->_ValidationFields with field names that exist in the $PostedFields collection.
defineValidationRules ( array $PostedFields, boolean $Insert = false ) : array	Get all of the validation rules that apply to a given set of data.

Method Details

__construct() public method

Class constructor. Optionally takes a schema definition to generate validation rules for.

public __construct ( Gdn_Schema \| array $Schema = false, $ResetOnValidate = false )
$Schema	Gdn_Schema \| array	A schema object to generate validation rules for.

addRule() public method

If $RuleName already exists, this method will overwrite the existing rule. There are some special cases: 1. If the $Rule begins with "function:", when the rule is evaluated on a field, it will strip the "function:" from the $Rule and execute the remaining string name as a function with the field value passed as the first parameter and the related field properties as the second parameter. ie. "function:MySpecialValidation" will evaluate as MySpecialValidation($FieldValue, $FieldProperties). Any function defined in this way is expected to return boolean TRUE or FALSE. 2. If $Rule begins with "regex:", when the rule is evaluated on a field, it will strip the "regex:" from $Rule and use the remaining string as a regular expression rule. If a match between the regex rule and the field value is made, it will validate as TRUE. 3. Predefined $RuleNames are: RuleName Rule ======================================================================== Required Will not accept a null or empty value. Email Will validate against an email regex. Date Will only accept valid date values in a variety of formats. Integer Will only accept an integer. Boolean Will only accept 1 or 0. Decimal Will only accept a decimal. Time Will only accept a time in HH:MM:SS or HH:MM format. Timestamp Will only accept a valid timestamp. Length Will not accept a value longer than $Schema[$Field]->Length. Enum Will only accept one of the values in the $Schema[$Field]->Enum array.

public addRule ( string $RuleName, string $Rule )
$RuleName	string	The name of the rule to be added.
$Rule	string	The rule to be added. These are in the format of "function:FunctionName" or "regex:/regex/". Any function defined here must be included before the rule is enforced or the application will cause a fatal error.

addValidationField() protected method

Adds a fieldname to the $this->_ValidationFields collection.

protected addValidationField ( string $FieldName, array $PostedFields )
$FieldName	string	The name of the field to add to the $this->_ValidationFields collection.
$PostedFields	array	The associative array collection of field names to examine for the value of $FieldName.

addValidationResult() public method

Add a validation result (error) to the validation.

public addValidationResult ( string $FieldName, string $ErrorCode = '' )
$FieldName	string	The name of the form field that has the error.
$ErrorCode	string	The translation code of the error. Codes that begin with an '@' symbol are treated as literals and not translated.

applyRule() public method

Applies a $RuleName to a $FieldName. You can apply as many rules to a field as you like.

public applyRule ( string $FieldName, mixed $RuleName, mixed $CustomError = '' )
$FieldName	string	The name of the field to apply rules to.
$RuleName	mixed	The rule name (or array of rule names) to apply to the field.
$CustomError	mixed	A custom error message you might want to apply to a field if the rule causes an error to be caught.

applyRuleTo() protected method

Apply a rule to the given rules array.

protected applyRuleTo ( array &$Array, string $FieldName, string $RuleName, string $CustomError = '' )
$Array	array	The rules array to apply the rule to. This should be either `$this->_FieldRules` or `$this->_SchemaRules`.
$FieldName	string	The name of the field that the rule applies to.
$RuleName	string	The name of the rule.
$CustomError	string	A custom error string when the rule is broken.

applyRulesBySchema() protected method

The {@link Gdn_Validation::$_SchemaRules} are filled with rules based on the properties of each field in the table schema.

protected applyRulesBySchema ( )

applySchema() public method

Allows the explicit definition of a schema to use.

Deprecation: This method has been deprecated in favor of {@link Gdn_Validation::SetSchema()}.

public applySchema ( array $Schema )
$Schema	array

defineValidationFields() protected method

Fills $this->_ValidationFields with field names that exist in the $PostedFields collection.

protected defineValidationFields ( array $PostedFields, boolean $Insert = false ) : array
$PostedFields	array	The associative array collection of field names to add.
$Insert	boolean	A boolean value indicating if the posted fields are to be inserted or updated. If being inserted, the schema's required field rules will be enforced.
return	array	Returns the subset of {@link $PostedFields} that will be validated.

defineValidationRules() protected method

Get all of the validation rules that apply to a given set of data.

protected defineValidationRules ( array $PostedFields, boolean $Insert = false ) : array
$PostedFields	array	The data that will be validated.
$Insert	boolean	Whether or not this is an insert.
return	array	Returns an array of `[$Field => [$Rules, ...]`.

getSchemaRules() public method

Get all of the rules as defined by the schema.

public getSchemaRules ( ) : array
return	array	Returns an array in the form `[$FieldName => [$Rules, ...]`.

reset() public method

Reset the validation results to an empty array.

public reset ( )

resetOnValidate() public method

Whether or not the validation results etc should reset whenever {@link Validate()} is called.

public resetOnValidate ( ) : boolean
return	boolean	Returns true if we reset or false otherwise.

results() public method

Returns the $this->_ValidationResults array. You must use this method because the array is read-only outside this object.

public results ( boolean $Reset = false ) : array
$Reset	boolean	Whether or not to clear the validation results.
return	array	Returns an array of validation results (errors).

resultsArray() public method

Get the validation results as an array of error messages.

public resultsArray ( ) : array
return	array	Returns an array of error messages or an empty array if there are no errors.

resultsAsArray() public static method

Expand the validation results into a single-dimension array.

public static resultsAsArray ( array $results ) : array
$results	array	The validation results to expand.
return	array	Returns an array of error messages.

resultsAsText() public static method

Format an array of validation results as a string.

public static resultsAsText ( array $results ) : string
$results	array	An array of validation results returned from {@link Gdn_Validation::Results()}.
return	string	Returns the validation results as a string.

resultsText() public method

Get the validation results as a string of text.

public resultsText ( ) : string
return	string	Returns the validation results.

schemaValidationFields() public method

Returns an array of field names that are in both $this->_ValidationFields AND $this->_Schema.

public schemaValidationFields ( ) : array
return	array	Returns an array of fields and values that were validated and in the schema.

setResetOnValidate() public method

Set whether or not the validation results etc should reset whenever {@link Validate()} is called.

public setResetOnValidate ( boolean $ResetOnValidate ) : Gdn_Validation
$ResetOnValidate	boolean	True to reset or false otherwise.
return	Gdn_Validation	Returns `$this` for fluent calls.

setSchema() public method

Set the schema for this validation.

public setSchema ( Gdn_Schema \| array $Schema ) : Gdn_Validation
$Schema	Gdn_Schema \| array	The new schema to set.
return	Gdn_Validation	Returns `$this` for fluent calls.

setSchemaProperty() public method

Allows you to explicitly set a field property on $this->_Schema. Can be useful when adding rules to fields (ie. a maxlength property on a db's text field).

public setSchemaProperty ( string $FieldName, string $PropertyName, mixed $Value )
$FieldName	string	The name of the field that we are setting a property for.
$PropertyName	string	The name of the property being set.
$Value	mixed	The value of the property to set.

unapplyRule() public method

Remove a validation rule that was added with {@link Gdn_Validation::ApplyRule()}.

public unapplyRule ( $FieldName, boolean $RuleName = false )
$FieldName
$RuleName	boolean

validate() public method

Examines the posted fields, defines $this->_ValidationFields, and enforces the $this->Rules collection on them.

public validate ( array $PostedFields, boolean $Insert = false ) : boolean
$PostedFields	array	An associative array of posted fields to be validated.
$Insert	boolean	A boolean value indicating if the posted fields are to be inserted or updated. If being inserted, the schema's required field rules will be enforced.
return	boolean	Whether or not the validation was successful.

validateRule() public static method

Execute a single validation rule and return its result.

public static validateRule ( mixed $Value, string $FieldName, string \| array $Rule, string $CustomError = false ) : boolean \| string
$Value	mixed	The value to validate.
$FieldName	string	The name of the field to put into the error result.
$Rule	string \| array	The rule to validate which can be one of the following. - string: The name of a function used to validate the value. - 'regex:': The regular expression used to validate the value. - array: An array with the following keys: - Name: The name of the function used to validate. - Args: An argument to pass to the function after the value.
$CustomError	string	A custom error message.
return	boolean \| string	One of the following - TRUE: The value passed validation. - string: The error message associated with the error.

validationFields() public method

Returns the an array of fieldnames that are being validated.

public validationFields ( ) : array
return	array

Property Details

$_FieldRules protected property

An associative array of $FieldName => array($RuleName1, $RuleNameN) rules to be applied to fields. These are rules that have been explicitly called with {@link Gdn_Validation::ApplyRule()}.

protected $_FieldRules

$_ResetOnValidate protected property

Whether or not to reset the validation results on validate.

protected $_ResetOnValidate

$_Rules protected property

The collection of validation rules in the format of $RuleName => $Rule. This list can be added to with $this->AddRule($RuleName, $Rule).

protected $_Rules

$_Schema protected property

The schema being used to generate validation rules.

protected $_Schema

$_SchemaRules protected property

An associative array of $FieldName => array($RuleName1, $RuleNameN) rules to be applied to fields. These are rules that come from the current schema that have been applied by {@link Gdn_Validation::ApplyRulesBySchema()}.

protected $_SchemaRules

$_ValidationFields protected property

An associative array of fieldname => value pairs that are being validated. In order for a field to become a part of this collection, it must either be present in the defined schema, or have a rule defined in $this->_FieldRules.

protected $_ValidationFields

$_ValidationResults protected property

An array of FieldName => Reason arrays that describe which fields failed validation and which functions/regex caused them to fail.

protected $_ValidationResults