README

A WordPress PHP Composer Package that provides you with an easy way to validate data against a set of rules and generate error messages.

Installation

You can install Nomad Validate in your project by using composer.

$ composer require jakesutherland/nomad-validate

Dependencies

Nomad Validate depends on Nomad Helpers for various functions and utilities and needs to be installed in order to run.

If for some reason you didn't install Nomad Validate via Composer as a required package in your project, you will still need to run composer install to install it's dependencies as they are not included in the repository.

Documentation

Nomad Validate has one simple function that you can use to validate data against a set of rules.

Example Usage

Each data item must have each of the following arguments: key, label, value, and rules.

You can optionally overwrite rule error messages through the error_messages argument and specify the rule key and your custom message. You can see this in the terms example below.

<?php

use function Nomad\Validate\nomad_validate;

$validated = nomad_validate( array(
	'first_name' => array(
		'key'   => 'first_name',
		'label' => 'First Name',
		'value' => $_POST['first_name'],
		'rules' => array( 'required', 'minlength:2', 'maxlength:20' ),
	),
	'last_name' => array(
		'key'   => 'last_name',
		'label' => 'Last Name',
		'value' => $_POST['last_name'],
		'rules' => array( 'required', 'minlength:2', 'maxlength:50' ),
	),
	'email_address' => array(
		'key'   => 'email_address',
		'label' => 'Email Address',
		'value' => $_POST['email_address'],
		'rules' => array( 'required', 'email' ),
	),
	'terms' => array(
		'key'            => 'terms',
		'label'          => 'Terms and Conditions',
		'value'          => $_POST['terms'],
		'rules'          => array( 'required' ),
		'error_messages' => array(
			'required' => 'You must agree to the terms and conditions.',
		),
	),
) );

if ( $validated->is_valid() ) {
	// Do something if everything is valid.
} else {
	// Do something if there was an error. Display error messages.
	$messages = $validated->get_all_error_messages();
}

Available Rules

Each rule is added to the rules argument individually for each piece of data.

Some rules contain arguments which let you further customize how the data is being compared and validated. To pass in an argument add a colon : after your rule key and then provide your argument value (<rule>:<argument>). You can see examples of rules with arguments below.

`boolean`

Usage: boolean, boolean:strict, boolean:truthy, boolean:falsey

Description: Checks that the value is a boolean value (true or false). You can also have it check for "truthy" (true, 1, 'true', '1', 'yes', 'on', 'truthy') or "falsey" (false, 0, 'false', '0', 'no', 'off', 'falsey') values.

`choices`

Usage: choices:value1,value2,value3

Description: Checks that the value is one of the provided choices. Each choice is separated by a comma.

`date`

Usage: date:Y-m-d

Description: Checks that the value is a date in the specified format. See https://www.php.net/manual/en/datetime.format.php for DateTime format options.

`email`

Usage: email

Description: Checks that the value is a valid email address.

`equals`

Usage: equals:value

Description: Checks that the value equals the provided value.

`letters`

Usage: letters

Description: Checks that the value only contains letters.

`matches`

Usage: matches:my_field_key

Description: Checks that the value matches the value of the specified key.

`maxlength`

Usage: maxlength:20

Description: Checks that the value character length is less than or equal to the provided number.

`max`

Usage: max:2021

Description: Checks that the value is less than or equal to the provided number.

`minlength`

Usage: minlength:10

Description: Checks that the value character length is greater than or equal to the provided number.

`min`

Usage: min:1900

Description: Checks that the value is greater than or equal to the provided number.

`numbers`

Usage: numbers

Description: Checks that the value only contains numbers.

`numeric`

Usage: numeric

Description: Checks that the value is numeric.

`regex`

Usage: regex:/^([A-Za-z0-9_\-\.]*)$/

Description: Checks that the value matches the given regular expression.

`required`

Usage: required

Description: Checks that the value is not empty.

`trim`

Usage: trim

Description: This is a special rule and simply trims whitespace from the left and right of the value.

`url`

Usage: url

Description: Checks that the value is a valid URL.

Available Hooks

`nomad/validate/{$key}`

/**
 * Filters the validity of a specific key.
 *
 * Gives you an opportunity to change whether or not a specific key is valid.
 *
 * @since 1.0.0
 *
 * @param boolean $valid Whether or not the specific key is valid.
 * @param string  $key   The data key.
 * @param string  $label Label used in error messages.
 * @param mixed   $value The data value.
 * @param array   $rules Rules to process the value against.
 */
$valid = apply_filters( "nomad/validate/{$key}", $valid, $key, $label, $value, $rules );

`nomad/validate/{$key}/{$rule_key}/error_message`

/**
 * Filter the error message for a specific data key and rule key.
 *
 * The filter is available if you want to use it, but it is easier
 * to pass in a custom message through the `error_messages`
 * argument when building your initial data array.
 *
 * @since 1.0.0
 *
 * @param string $error_message The error message that was generated.
 * @param string $key           The data key.
 * @param string $label         Label used in error messages.
 * @param mixed  $value         The data value.
 * @param string $rule_key      Rule key being processed.
 * @param string $argument      Argument for the rule being processed.
 */
$error_message = apply_filters( "nomad/validate/{$key}/{$rule_key}/error_message", $error_message, $key, $label, $value, $rule_key, $argument );

`nomad/validate/error_messages`

/**
 * Filter all error messages generated during validation, listed by data key.
 *
 * @since 1.0.0
 *
 * @param array Error messages generated during validation, listed by data key.
 */
$error_messages = apply_filters( 'nomad/validate/error_messages', $error_messages );

Changelog

v1.1.0

Updated Nomad_Validate class filename to be prefixed with class-.
Updated Nomad_Validate to be a final class.
Updated rules minnumber to min and maxnumber to max. Both are still backwards compatible.
Updated verbiage for choices rule error message.
Updated dependency Nomad Helpers to the latest version (1.2.0). This introduced the register_nomad_package() function that is now being used to register the Nomad Validate package.
Fixed choices rule to not also treat the value as if its required.

jakesutherland / nomad-validate

Maintainers

Details