A PHP library that allows for an easy and customizable way to validate data.

The code will run through an array of data and for each item will execute the specified validations. In the end any validations that failed will generate an error message that you can display.

All the validations and error messages can be customized, even the default ones, and you can create new ones "on the fly" very easily.

Add the following to your project's composer.json file:

{
    "require": {
        "pedrohenriques/data-validator": "1.*"
    }
}

Replacing the version with your preference.

1. Copy the src folder into your project.
2. Reference the DataValidator.php file on the webpages you wish to use the Data Validator using, for example, require_once("path/to/DataValidator.php").

In order to use the Data Validator create an instance of the DataValidator class using the code:

use DataValidator\DataValidator;

$validator = new DataValidator([string $json_path]);

With:

• $json_path: String with the path to the error_msg.json file. This file contains the default error messages for each validation type.
  If a path isn't provided the code will assume that the file is located at src/data/error_msg.json.

With:

• $data: Array with the data to be validated.
  
  
• $validations: Array with the desired validations for each of the $data entries (see below for the syntax).
  
  
• $single_fail: Boolean that controls whether all validations for a $data entry should be executed, or if they should stop when 1 fails.
  True will stop a $data entry's validations as soon as 1 fails and False will execute all validations for a $data entry, regardless of how many fail.
  By default the code will assume the value False.

The complete syntax is $validations = ["field;alias" => ["check_type1;value1;value2...", "check_type2;value1;value2...", ...], ...] where:

• field: The name of the desired $data entry. The names must match in both the $data and $validations array.
  
  
• alias: [optional] The alias for the field.
  If provided, the alias will be used in the error messages instead of the field name.
  If not provided, the field name will be used in the error messages.
  
  
• check_type: The validation name for the check in question.
  
  
• value: One value that will be made available to the validation code and the error messages.
  If the desired value is one of the $data entries use the format %field%, which will be replaced by that field's $data entry.

This repository comes with the following validations available:

Given the inputs:

$data = [
	"user_name" => "Pedro Henriques",
	"email" => "pedro@pedrojhenriques.com",
	"password" => "pw123",
	"password_conf" => "pw456",
	"gender" => "male",
	"commission" => "200",
	"planet" => "Mars"
];

and the validations:

$validations = [
	"user_name;User Name" => ["required", "max_len;50"],
	"email;Email" => ["required", "email"],
	"password;Password" => ["required", "min_len;6", "max_len;50"],
	"password_conf;Password Confirmation" => ["match;%password%"],
	"gender;Gender" => ["in;male;female"],
	"commission;Commission" => ["required", "range;0;100"],
	"planet;Planet of Origin" => ["required", "match;Earth"],
];

the following errors will be generated:

Array
(
    [password] => Array
        (
            [0] => The length of the Password provided is too short.
        )

    [password_conf] => Array
        (
            [0] => The Password Confirmation provided doesn't match Password.
        )

    [commission] => Array
        (
            [0] => The value provided for the Commission field must be between 0 and 100.
        )

    [planet] => Array
        (
            [0] => The Planet of Origin provided doesn't match Earth.
        )

)

Assuming $validator contains an instance of the DataValidator class.

The following methods allow for the execution of the validations and access to their results:

NOTE: These methods are used to customize the Data Validator. For further detail consult the topic Customizing the Data Validator below.

It's possible to customize the validations as well as the error messages in 2 ways:

1. Persistent: Adding a new validation as a class and an error message as an entry in the error_msg.json file.
2. Temporary: Registering a new validation as a temporary function and an error message as a temporary string.

When a validation is called, the code will first look for a temporary function with the same check type. If no matching function can be found the code will look for a defined class with a matching name (see below for naming convention).
This means that custom temporary validations will have priority over the persistent validations. If you wish to change the behavior of a persistent validation, register a temporary function with the same check type.

These classes should implement the interface `iValidation`, located at `src/interfaces/interfaces.php`.  

**NOTE:** The code expects a validation class to belong in the **DataValidator\Validations** namespace.

As an example:  
```
namespace DataValidator\Validations;

use DataValidator\Interfaces\iValidation;

class ValMyClass implements iValidation {
	public function runCheck($field, $input, array $params) {
		// validation code goes here!
		// return True if the validation passed or False if it failed.
	}
}
```  

The code will automatically look for, and include, a file with the same name as the validation class in the directory `src/validations`.  
However, as long as the classes are defined by the time the code calls them, they don't need to be in a file with the same name, or in the default directory.  

**EX:**  
For a check type called `min_len` the code expects a class named `ValMinLen` and will automatically look for and include a file named `ValMinLen.php`.  
For a check type called `required` the code expects a class named `ValRequired` and will look for a file named `ValRequired.php`.  

The `$check_type` parameter must exactly match the check type provided in the `$validations` array of the `DataValidator` class' constructor.  

The `$function` parameter must be a function that returns `True` if the check passed or `False` if it failed.  
The function will be given the same parameters as the `runCheck()` method of the `iValidation` interface, located at `src/interfaces/interfaces.php`, so in order to have access to that information inside this function those parameters must be defined in the function's declaration.  
The function can be lambda/anonymous or "named".  

**EX:**  
The following code will register a new temporary validation, accessible as check type `custom_val`:  
```
$validator->addValidation("custom_val", function($field, $input, array $params) {
	// validation code goes here!
	// return True if the validation passed or False if it failed.
});
```

- `$field`: String with the name of the $data entry being validated.<br><br>
- `$input`: String with the value of the $data entry being validated. If `$field` doesn't exist in `$data`, then `$input` will be `null`.<br><br>
- `$params`: Array with all validation values provided in the `$validations` array (zero-based indexed).  

Given the following code:

$data = [
	"commission" => "20",
	"tax" => "25"
];

$validations = [
	"commission;Commission Perc." => ["custom_val;10;100;47"],
	"tax;Tax Perc." => ["match;%commission%"]
];

The information available to the validation method/function is:

• For $data["commission"] and check type custom_val:
  
  • $field: "commission"
    
    
  • $input: "20"
    
    
  • $params: [0 => "0", 1 => "100", 2 => "47"]

When an error message is generated, the code will first look for a temporary string with the same check type and field. If no matching string can be found the code will look for the persistent message with a matching name.
This means that custom temporary strings will have priority over the persistent messages. If you wish to change the content of a persistent message, register a temporary string with the same check type.

The `$check_type` parameter must exactly match the check type provided in the `$validations` array of the `DataValidator` class' constructor.

- `%field%`: Will be replaced by the name of the field were the error occurred.  
	Will use the field's alias, if one was provided.<br><br>
- `%check_type%`: Will be replaced by the check type were the error occurred.<br><br>
- `%input%`: Will be replaced by the $data value being validated that generated the error.<br><br>
- `%params[key]%`: Will be replaced by the actual validation value in use with the given "key"<br><br>
- `%%key%%`: Will be replaced by the value in $validations with the given "key"  
	If the value was another field, it's alias will be used, if one was provided.<br><br>

**NOTE:** If "key" is `...`, then all available values for the failed validation will be displayed, separated by `, `

Given the following code:

$data = [
	"commission" => "20",
	"tax" => "25"
];

$validations = [
	"commission;Commission Perc." => ["custom_val;10;100;47"],
	"tax;Tax Perc." => ["match;%commission%"]
];

The information available to the error messages is:

• For $data["commission"] and check type custom_val:
  
  • %field%: Commission Perc.
    
    
  • %check_type%: custom_val
    
    
  • %input%: 20
    
    
  • %params[0]%: 10
    
    
  • %params[1]%: 100
    
    
  • %params[2]%: 47
    
    
  • %params[...]%: 10, 100, 47
    
    
  • %%0%%: 10
    
    
  • %%1%%: 100
    
    
  • %%2%%: 47
    
    
  • %%...%%: 10, 100, 47

It's possible to configure certain combinations of check types and input values that will "short-circuit" the rest of the validations, preventing them from being executed.

In order to register a temporary short-circuit rule use the method addShortCircuit, listed above as an advanced method.

The permanent short-circuit combinations are defined in the $short_circuit_rules variable, located at the start of the DataValidator class' definition.

By default this variable has the following value:

$short_circuit_rules = [
	["check" => "required", "input" => [null, ""], "run_check" => true],
	["check" => "!required", "input" => [null, ""], "run_check" => false]
];

The first entry reads as follows: "if the field being validated has the required check and the $data entry is either null or "", then execute the required check but no others."
This prevents multiple error messages from being generated and checks being executed unnecessarily since there is no input value to validate and one was required.
Note that by still executing the required check, which will fail, there will still be an error message being generated for that check.

The second entry reads as follows: "if the field being validated doesn't have the required check and the $data entry is either null or "", then don't execute the required check or any other checks."
This prevents an optional field that was left empty from being validated and potentially generating error messages, when no validation is required.
However, if the field was provided ($input will be a non empty string) then any relevant checks will be executed.
Note that an ! is used to denote the absence of a check.