<commit_before># WFV - WordPress Form Validation
[![Build Status](https://travis-ci.org/macder/wp-form-validation.svg?branch=master)](https://travis-ci.org/macder/wp-form-validation)

Elegant input & validation API.

**NOTICE:**<br>
User documentation is being moved to [https://macder.github.io/wfv/](https://macder.github.io/wfv/)

Info on [Development & Testing](https://github.com/macder/wp-form-validation/tree/master/tests)


# Table of Contents
* [Features](#features)
* [Basic Example](#basic-example)
* [Install](#install)
* [Usage](#usage)
  * [Rules](#rules)
  * [Custom Rules](#custom-rules)
  * [Custom Feedback](#custom-feedback)
  * [Validation Hooks](#validation-hooks)
  * [Markup a Form](#create-a-form-somewhere-in-your-theme)
  * [Form Composite](#form-composite)
  * [User Input](#user-input)
  * [Auto Populate](#auto-populate)
  * [Errors](#validation-errors)

## Features
* 32 built-in [Valitron](https://github.com/vlucas/valitron#built-in-validation-rules) rules
* Custom rules
* Custom error messages
* [Helper methods](#user-input) for safe output
* Auto populate
* Multiple forms
* Validation Hooks
* Self POST - no redirects, no GET vars, no sessions, no cookies
* Lightweight - Only one dependency (WordPress aside)
* [Unit tested core](https://github.com/macder/wp-form-validation/tree/master/tests) - More stable, quicker fixes, less bugs, more happy
* No rendered markup
* Developer freedom

## Basic example

`functions.php` or wherever:
```php
<?php

// declare the rules
$my_form = array(
  'rules'   => array(
    'first_name' => ['required'],
    'email'      => ['required', 'email']
  )
);

// validation pass
add_action( 'contact_form', 'my_form_valid' );
function my_form_valid( $form ) {
  // do something...
}

// validation fail
add_action( 'contact_form_fail', 'my_form_invalid' );
function my_form_invalid( $form ) {
  // do something...
}

// create the instance
wfv_create( 'contact_form', $my_form );

// $my_form is now an instance of WFV\Composite\Form:

```

Theme template:
```php
<form method="post">
  <input name="email" type="text">
  <?php $my_form->get_token_fields(); ?>
  <input type="submit" value="Send">
</form>
```

# Install

**Minimum Requirements:**
* WordPress 3.7
* PHP 5.4

*PHP 7.0 support for WordPress 4.0+*

**Recommended:**
* WordPress 4.7.x
* PHP 7.0

**Pre-release**

`$ git clone` or download `master` to `./wp-content/plugins`

`$ composer install`


# Usage

## Rules

```php
<?php
$my_form = array(
  'rules'   => array(
    'first_name' => ['required'],
    'email'      => ['required', 'email'],
  )
);
```

For available validation rules, reference the [Valitron](https://github.com/vlucas/valitron#built-in-validation-rules) doc.

## Custom Rules

Prepend `custom:` to rule, name of rule is the callback.
```php
<?php
$my_form = array(
  'rules'   => array(
    'phone'      => ['required', 'custom:phone'],
  )
);
```
Create the callback:
```php
<?php // phone field will validate only if the input is 'hi' ...how cruel

function wfv__phone( $value ) {
  return ( 'hi' === $value ) ? true : false;
}
```

## Custom Feedback

```php
<?php
$my_form = array(
  'rules'   => array(
    'email'     => ['required', 'email']
  ),

  // override an error message
  'messages' => [
    'email' => array(
      'required' => 'No email, no reply... get it?'
    )
  ]
);
```

## Validation Hooks

**Pass:**

```php
<?php // action hook and callback for validation pass

add_action( 'contact_form', 'contact_form_valid' );
function contact_form_valid( $form ) {
  // form input valid, do something...
}
```

**Fail:**
```php
<?php // action hook and callback for validation fail

add_action( 'contact_form_fail', 'contact_form_invalid' );
function contact_form_invalid( $form ) {
  // form input NOT valid, do something...
}
```

## Markup a Form

```html
<form name="contact_form" method="post">
  <input name="name" type="text">
  <input name="email" type="text">
  <textarea name="msg"></textarea>

  <?php $my_form->get_token_fields(); ?>
  <input type="submit" value="Submit">
</form>
```
The form must have the required token tag:
```php
<?php $my_form->get_token_fields(); ?>
```
This adds 2 hidden fields, nonce and action. The generated action field identifies the form to a validation instance.

## Form Entity
### `wfv_create( string $action, array $form )`

Pass by reference an instance of `WFV\FormComposite`.<commit_msg>readme - update method name in markup example<commit_after># WFV - WordPress Form Validation
[![Build Status](https://travis-ci.org/macder/wp-form-validation.svg?branch=master)](https://travis-ci.org/macder/wp-form-validation)

Elegant input & validation API.

**NOTICE:**<br>
User documentation is being moved to [https://macder.github.io/wfv/](https://macder.github.io/wfv/)

Info on [Development & Testing](https://github.com/macder/wp-form-validation/tree/master/tests)


# Table of Contents
* [Features](#features)
* [Basic Example](#basic-example)
* [Install](#install)
* [Usage](#usage)
  * [Rules](#rules)
  * [Custom Rules](#custom-rules)
  * [Custom Feedback](#custom-feedback)
  * [Validation Hooks](#validation-hooks)
  * [Markup a Form](#create-a-form-somewhere-in-your-theme)
  * [Form Composite](#form-composite)
  * [User Input](#user-input)
  * [Auto Populate](#auto-populate)
  * [Errors](#validation-errors)

## Features
* 32 built-in [Valitron](https://github.com/vlucas/valitron#built-in-validation-rules) rules
* Custom rules
* Custom error messages
* [Helper methods](#user-input) for safe output
* Auto populate
* Multiple forms
* Validation Hooks
* Self POST - no redirects, no GET vars, no sessions, no cookies
* Lightweight - Only one dependency (WordPress aside)
* [Unit tested core](https://github.com/macder/wp-form-validation/tree/master/tests) - More stable, quicker fixes, less bugs, more happy
* No rendered markup
* Developer freedom

## Basic example

`functions.php` or wherever:
```php
<?php

// declare the rules
$my_form = array(
  'rules'   => array(
    'first_name' => ['required'],
    'email'      => ['required', 'email']
  )
);

// validation pass
add_action( 'contact_form', 'my_form_valid' );
function my_form_valid( $form ) {
  // do something...
}

// validation fail
add_action( 'contact_form_fail', 'my_form_invalid' );
function my_form_invalid( $form ) {
  // do something...
}

// create the instance
wfv_create( 'contact_form', $my_form );

// $my_form is now an instance of WFV\Composite\Form:

```

Theme template:
```php
<form method="post">
  <input name="email" type="text">
  <?php $my_form->get_token_fields(); ?>
  <input type="submit" value="Send">
</form>
```

# Install

**Minimum Requirements:**
* WordPress 3.7
* PHP 5.4

*PHP 7.0 support for WordPress 4.0+*

**Recommended:**
* WordPress 4.7.x
* PHP 7.0

**Pre-release**

`$ git clone` or download `master` to `./wp-content/plugins`

`$ composer install`


# Usage

## Rules

```php
<?php
$my_form = array(
  'rules'   => array(
    'first_name' => ['required'],
    'email'      => ['required', 'email'],
  )
);
```

For available validation rules, reference the [Valitron](https://github.com/vlucas/valitron#built-in-validation-rules) doc.

## Custom Rules

Prepend `custom:` to rule, name of rule is the callback.
```php
<?php
$my_form = array(
  'rules'   => array(
    'phone'      => ['required', 'custom:phone'],
  )
);
```
Create the callback:
```php
<?php // phone field will validate only if the input is 'hi' ...how cruel

function wfv__phone( $value ) {
  return ( 'hi' === $value ) ? true : false;
}
```

## Custom Feedback

```php
<?php
$my_form = array(
  'rules'   => array(
    'email'     => ['required', 'email']
  ),

  // override an error message
  'messages' => [
    'email' => array(
      'required' => 'No email, no reply... get it?'
    )
  ]
);
```

## Validation Hooks

**Pass:**

```php
<?php // action hook and callback for validation pass

add_action( 'contact_form', 'contact_form_valid' );
function contact_form_valid( $form ) {
  // form input valid, do something...
}
```

**Fail:**
```php
<?php // action hook and callback for validation fail

add_action( 'contact_form_fail', 'contact_form_invalid' );
function contact_form_invalid( $form ) {
  // form input NOT valid, do something...
}
```

## Markup a Form

```html
<form name="contact_form" method="post">
  <input name="name" type="text">
  <input name="email" type="text">
  <textarea name="msg"></textarea>

  <?php $my_form->token_field(); ?>
  <input type="submit" value="Submit">
</form>
```
The form must have the required token tag:
```php
<?php $my_form->get_token_fields(); ?>
```
This adds 2 hidden fields, nonce and action. The generated action field identifies the form to a validation instance.

## Form Entity
### `wfv_create( string $action, array $form )`

Pass by reference an instance of `WFV\FormComposite`.
{'fraction_non_alphanumeric': 0.17496893708347452, 'fraction_numerical': 0.003388681802778719, 'mean_word_length': 4.132753623188406, 'pattern_counts': {'":': 0, '<': 47, '<?xml version=': 0, '>': 65, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '152658', 'n_tokens_mistral': 3072, 'n_tokens_neox': 2914, 'n_words': 801}