Luminova Framework

PHP Luminova: User Input Validation Module

Last updated: 2024-08-28 22:44:01

With the input Validation class, you can validate the user-submitted data before saving it to the database. To do that you will have to set validation rules for each input field and optional error me

The Input Validation class in the Luminova Framework provides a robust mechanism for validating user-submitted data before processing or storing it in a database. With this class, you can define validation rules for each input field along with optional error messages, ensuring that the data meets your application's requirements and standards.

Validation Rules

You can set validation rules for input fields using a variety of predefined validation rules, including required fields, maximum and minimum lengths, alphanumeric characters, email addresses, integers, and more. Rules can be added individually or set from an array, allowing for flexible configuration. Additionally, custom validation rules can be defined using callback functions.

Defining Rules

Validation rules are specified by separating each rule with a pipe | and providing parameters in parentheses when needed. Rules can be applied to individual fields or set globally using associative arrays, with the option to specify custom error messages for each rule.

Error Message Formatting

Error messages can include placeholders such as {field}, {value}, and {rule} to dynamically insert relevant information about the validation error. This makes error messages more informative and context-aware, enhancing the user experience.

Formatting Example

$this->validate->messages = [
    'email' => [
        'required' => 'The {field} field is required.',
        'email' => 'The value "{value}" is not a valid {rule}.'
    ]
];

In this example:

  • {field} will be replaced with the name of the field being validated.
  • {value} will be replaced with the actual value that failed validation.
  • {rule} will be replaced with the name of the validation rule that was violated.

Usage Examples

Setting up validation rules and optional response messages:

// app/Controllers/SignUpController.php

<?php 
namespace App\Controllers;

use Luminova\Base\BaseController;
class SignUpController extends BaseController
{
    protected function onCreate(): void 
    {
        $this->validate->rules = [
            'email' => 'required|email',
            'phone' => 'required|phone(10)',
            'name' => 'required|alphabet',
        ];

        $this->validate->messages = [
            'email' => [
                'required' => 'Email is required.',
                'email' => 'Invalid email address.'
            ],
            'phone' => [
                'required' => 'Phone number is required.',
                'phone' => 'Invalid phone number.'
            ],
            'name' => [
                'required' => 'Name is required.',
                'alphabet' => 'Name contains unsupported characters.'
            ],
        ];
    }
}

Performing validation based on the defined rules:

// app/Controllers/SignUpController.php

<?php 
public function create(): int 
{
    $body = $this->request->getBody();

    if ($this->validate->validate($body)) {
        echo 'Validation passed.';
    } else {
        echo 'Validation failed.';
    }
    //...
}

Retrieving validation error information when validation fails:

Get all validation errors:

<?php 
var_dump($this->validate->getErrors());

Get the first validation error message:

<?php 
echo $this->validate->getError(0, 'message');

Get the first validation error by field and error index. This will print the first field with an error and the first error rule:

<?php 
echo $this->validate->getErrorLine(0);

Get information about the first field that failed validation:

<?php 
var_dump($this->validate->getErrorField(0, 0));

These examples demonstrate how to set up and use validation rules, handle validation responses, and retrieve detailed error information in a structured and meaningful way.


Validation Class


Properties

rules

Define the validation rules for each form input field. The input field name should be the array key, and the validation rule(s) should be the value.

public array<string,string> $rules = [];

messages

Define custom error messages for each validation rule. The array key should be the input field name, and the value should be an array where each key is a validation rule name, and the value is the corresponding error message.

If no custom error messages are provided, a default error message will be used, such as Validation failed for field: 'email', while validating [email].

public array<string,array<string,string>> $messages = [];

Methods

validate

Do the validation based on defined rules and input request body.

public validate(array&lt;string,mixed&gt; $input, array&lt;string,string&gt;|null $rules = null): bool

Parameters:

ParameterTypeDescription
$inputarray<string,mixed>The input request body to validate (e.g, $this->request->getBody(), $_POST, $_GET, $_REQUEST).
$rulesarray<string,string>|nullOptional array of rules to override initialized rules (default NULL).

Return Value:

bool - Returns true if all validation rules are passed, otherwise false.


isPassed

Check if all validation rules passed.

public isPassed(): bool

Return Value:

bool - Returns true if all validation rules are passed, otherwise false.


setRules

Set validation rules from an array with optional error messages.

public setRules(array&lt;int,string&gt; $rules, array&lt;string,array&gt; $messages = []): self

Parameters:

ParameterTypeDescription
$rulesarray<int,string>The array of validation rules (e.g, ['email' => 'string\|email', 'name' => 'required']).
$messagesarray<string,array<string,string>>Optional error messages for validation rules (e.g, ['email' => ['string' => '...', 'email' => '...'], 'name' => ['required' => '...']]).

Return Value:

ValidatorInterface - Return instance of the Validation class.


addRule

Add a rule with an optional error message. This method can be called multiple times with different field name and rule.For $messages arguments, the array key will be the rule's name while the value is the message to display if form field fails the validation rule.

public addRule(string $field, string $rules, array&lt;string,string&gt; $messages = []): self

Parameters:

ParameterTypeDescription
$fieldstringThe form input field name (e.g, name, email).
$rulesstringThe input field validation rules (e.g, required|string|email).
$messagesarray<string,string>Optional validation error message for the each rule.

Return Value:

ValidatorInterface - Return instance of the Validation class.


getErrors

Get all validation error messages.

public getErrors(): array

Return Value:

array<string,array> - Return array of validation error messages, otherwise empty array.


getError

Get the error message, rule or field for a specific input field or using field index position.

public getError(string|int $fieldIndex = 0, string $type = 'message'): string

Parameters:

ParameterTypeDescription
$fieldIndexstring|intThe input field by index position or the input filed name (default: 0).
$typestringThe type of error detail to return (default: message).

Return Value:

string - Return an error details based on $type for the specified field.

Supported Types:

  • message - Return the error message.
  • rule - Return the rule name associated with the error.
  • field - Return the input field name associated with the error.

getErrorLine

Get the error message at the specified field and error indexes.If 0 is passed on both arguments, it will return the first input field that has error, and the first error rule.

public getErrorLine(string|int $indexField = 0, int $errorIndex = 0): string;

Parameters:

ParameterTypeDescription
$fieldIndexintThe input field by index number or input filed name (default: 0).
$errorIndexstring|intThe error index for current field if has multiple rules (default: 0).

Return Value:

string - Error message.


getErrorField

Get information about the validation error at the specified field index or field name.When passed an integer index, it will return the first validation error.When passed a string field name, it will return the validation error related to that field name.

public getErrorField(string|int $fieldIndex = 0): array

Parameters:

ParameterTypeDescription
$fieldIndexstring|intThe input field by index number or input filed name.

Return Value:

array<int,array> - Return array error information related to the field validation.

Return Keys:

  • message - The error message associated with the field.
  • rule - The rule associated with the field and error.
  • field - The validation field.

Validation Rules

These rules provide useful validation for various types of data, ensuring that your application processes only valid and expected input.

RuleParameterDescription
nonevoidIgnore the field and return true or aliasnullable.
requiredvoidThe field is required and cannot be empty.
max()integerThe field's maximum allowed length or alias max_length().
min()integerThe field's minimum allowed length or alias min_length().
alphanumericvoidThe field should contain only alphanumeric characters (a-Z, A-Z, 0-9).
emailvoidThe field must be a valid email address.
stringvoidThe field must be a valid string value.
integer()stringThe field must be an integer value. Optional parameter to specify if it should be positive or negative.
equals()stringThe field value must match the value of another specified field.
urlvoidThe field must be a valid URL.
alphabetvoidThe field must contain only alphabetic characters (a-Z, A-Z).
uuid()integerThe field value must be a valid UUID string. Optional parameter to specify the UUID version.
length()integerThe field value must have the exact specified length, alias exact_length().
in_array()stringThe field value must be in the specified array list.
is_listvoidThe field value must be a valid string list (e.g, foo,bar,baz,bra).
keys_exist()stringThe field's array values must match the specified validation list.
callback()callableA callback function myFunction(value, field) that returns a boolean value.
ip()integerThe field value must be a valid IP address. Optional parameter to specify the IP version (4, 6 or 0 for any).
decimalvoidThe field must be a valid decimal value.
match()regexThe field value must match the specified regular expression pattern.
fallback()mixedIf the field value is empty, replace it with the default value. If the parameter is empty, an empty string will be used.
phonestring|voidThe field value must be a valid phone number, optionally pass minimum allow length for phone number
binaryVoidThe field value must be a valid binary value.
hexadecimalvoidThe field value must be a valid hexadecimal value.
arrayvoidThe field value must be a valid array.
jsonvoidThe field value must be a valid JSON object.
path()string|voidThe field value must be a valid directory path. If the parameter is readable, it will check if the path is readable or writable.
scheme()stringThe field value must match the specified URL scheme.

Custom Validation Rule

To define your own custom validation rule using the callback method, ensure your callback is callable and returns true for a successful validation or false for a failed validation.

Additionally, the callback function should be designed to accept two parameters:

  • value (mixed) - The first parameter is the value submitted.
  • field (string) - The second parameter is the input field name.

Example

Function to perform your custom validation logic.

// app/Utils/Global.php

function myCustomRule(mixed $value, string $field): bool 
{
    if ($value === 'expected_value') {
        return true;
    }
    return false;
}

Adding your function as a validation rule.

$this->validate->rules = [
    'custom_field' => 'required|callback(myCustomRule)',
];