README

🔦 HTMLFormValidation

Description

HtmlFormValidator is a very easy to use PHP library that will help you to validate your <form> data and you can use this independent from your framework of choice.

Install via "composer require"

composer require voku/html-form-validator

How does this work?

First you need to generate a html form, that's completely your part. You can write it manually or you can generate with a framework or a library, it doesn't matter.
Then we use DOM Parsing via voku/simple_html_dom, to detect the current validator and filter rules directly from the html.
And finally, we use Respect/Validation to validate the form.

Simple Example

use voku\HtmlFormValidator\Validator;

require_once 'composer/autoload.php';

$html = '
<form id="music" method="post">
  <label>Artist:
    <select name="top5" required="required">
      <option>Heino</option>
      <option>Michael Jackson</option>
      <option>Tom Waits</option>
      <option>Nina Hagen</option>
      <option>Marianne Rosenberg</option>
    </select>
  </label>
</form>
';

$rules = $formValidator->getAllRules();
static::assertSame(
    [
        'music' => [
            'top5' => 'in(' . \serialize(['Heino','Michael Jackson','Tom Waits','Nina Hagen','Marianne Rosenberg',]) . ')',
        ],
    ],
    $rules
);

// --- valid

// fake some data
$_POST = [
    'top5' => 'Heino',
];
$formValidatorResult = $formValidator->validate($_POST);
static::assertSame([], $formValidatorResult->getErrorMessages());

// --- invalid

// fake some data
$_POST = [
    'top5' => 'fooooo',
];
$formValidatorResult = $formValidator->validate($_POST);
static::assertSame(
    [
        'top5' => [
            '"fooooo" must be in { "Heino", "Michael Jackson", "Tom Waits", "Nina Hagen", "Marianne Rosenberg" }',
        ],
    ],
    $formValidatorResult->getErrorMessages()
);

Extended Example

use voku\HtmlFormValidator\Validator;

require_once 'composer/autoload.php';

$html = '
<form id="register" method="post">
    <label for="email">Email:</label>
    <input
        type="email"
        id="email"
        name="user[email]"
        value=""
        data-validator="email"
        data-filter="trim"
        data-error-class="error-foo-bar"
        data-error-message--email="Your email [%s] address is not correct."
        data-error-template-selector="span#email-error-message-template"
        required="required"
    >
    <span style="color: red;" id="email-error-message-template"></span>
    
    <label for="username">Name:</label>
    <input
        type="text"
        id="username"
        name="user[name]"
        value=""
        data-validator="notEmpty|maxLength(100)"
        data-filter="strip_tags(<p>)|trim|escape"
        data-error-class="error-foo-bar"
        data-error-template-selector="span#username-error-message-template"
        required="required"
    >
    <span style="color: red;" id="username-error-message-template"></span>
    
    <label for="date">Date:</label>
    <input 
        type="text"
        id="date"
        name="user[date]"
        value=""
        data-validator="dateGerman|notEmpty"
        data-filter="trim"
        data-error-class="error-foo-bar"
        data-error-message--dateGerman="Date is not correct."
        data-error-message--notEmpty="Date is empty."
        data-error-template-selector="span#date-error-message-template"
        required="required"
    >
    <span style="color: red;" id="date-error-message-template"></span>
    
    <button type="submit">submit</button>
</form>
';

$formValidator = new Validator($html);

// fake some data
$_POST = [
    'user' => [
        'email' => 'foo@isanemail',
        'name'  => 'bar',
    ],
];

// validate the form
$formValidatorResult = $formValidator->validate($_POST);

// check the result
static::assertFalse($formValidatorResult->isSuccess());

// get the error messages
static::assertSame(
    [
        'user[email]' => ['Your email [foo@isanemail] address is not correct.'],
        'user[date]'  => [
            'Date is not correct.',
            'Date is empty.',
        ],
    ],
    $formValidatorResult->getErrorMessages()
);

// get the new html
static::assertSame(
    '
    <form id="register" method="post">
        <label for="email">Email:</label>
        <input 
                type="email" 
                id="email" 
                name="user[email]" 
                value="" 
                data-validator="email" 
                data-filter="trim" 
                data-error-class="error-foo-bar" 
                data-error-message--email="Your email [%s] address is not correct." 
                data-error-template-selector="span#email-error-message-template" 
                required="required" 
                aria-invalid="true"
        >            
        <span style="color: red;" id="email-error-message-template">Your email [foo@isanemail] address is not correct.</span>
                                
        <label for="username">Name:</label>
        <input 
                type="text" 
                id="username" 
                name="user[name]" 
                value="bar" 
                data-validator="notEmpty|maxLength(100)" 
                data-filter="strip_tags(<p>)|trim|escape" 
                data-error-class="error-foo-bar" 
                data-error-template-selector="span#username-error-message-template" 
                required="required" 
                aria-invalid="false"
        >            
        <span style="color: red;" id="username-error-message-template"></span>
                                
        <label for="date">Date:</label>
        <input 
                type="text" 
                id="date" 
                name="user[date]" 
                value="" 
                data-validator="dateGerman|notEmpty" 
                data-filter="trim" 
                data-error-class="error-foo-bar" 
                data-error-message--dategerman="Date is not correct." 
                data-error-message--notempty="Date is empty." 
                data-error-template-selector="span#date-error-message-template"
                required="required" 
                aria-invalid="true"
        >            
        <span style="color: red;" id="date-error-message-template">Date is not correct. Date is empty.</span>
                                
        <button type="submit">submit</button>
    </form>
    ',
    $formValidatorResult->getHtml()
);

Validator

You can use all validators from here.

e.g.: data-validator="date" || data-validator="' . \Respect\Validation\Rules\Date::class . '" (you need to lowercase the first letter from the class or you can use the class name itself)

You can combine validators simply via "|" ...

e.g.: data-validator="notEmpty|maxLength(100)"

PS: you can add arguments comma separated or you can use serialize -> something like that -> in(' . serialize($selectableValues) . ')

If you want to use the HTML5 validation e.g. for min or max values, or for e.g. email then you can use "auto".

e.g.: data-validator="auto"

By default we limit the submitted values to the values from the form e.g. for checkboxes, radios or select boxes. If you need to disable this, you can use "non-strict". (not recommended)

e.g.: data-validator="non-strict"

By default we use the error messages from the validation exception class, but you can use your own error messages via: "data-error-message--RULE_NAME_HERE" in the html.

e.g.: data-error-message--email="Email [%s] is not correct"

By default we don't add error messages into html output, but you can add the error messages with a css selector:

e.g.: data-error-template-selector="span#email-error-message-template"

By default we also don't add error classes, but you can add a new error class via:

e.g. data-error-class="error-foo-bar"

And if you need a more complex validation, then you can add simple-custom validations.

$formValidator->addCustomRule(
    'foobar',
    \Respect\Validation\Validator::allOf(
        \Respect\Validation\Validator::intVal(),
        \Respect\Validation\Validator::positive()
    )
);

e.g.: data-validator="foobar"

And if you need really complex validation, then you can create your own classes.

<?php

namespace Respect\Validation\Rules;

class CustomRule extends AbstractRule
{
  /**
   * @param string $value
   *
   * @return bool
   */
  public function validate($value)
  {
    return ($value === 'foobar');
  }

}

<?php

namespace Respect\Validation\Exceptions;

class CustomRuleException extends ValidationException
{
  public static $defaultTemplates = [
      self::MODE_DEFAULT  => [
          self::STANDARD => 'Invalid input... \'foobar\' is only allowed here... ',
      ],
      self::MODE_NEGATIVE => [
          self::STANDARD => 'Invalid input... \'foobar\' is not allowed here... ',
      ],
  ];
}

$formValidator->addCustomRule('foobar', \Respect\Validation\Rules\CustomRule::class);

e.g.: data-validator="foobar"

Filter

You can also use some simple filters, that will be applied on the input-data.

trim
escape (htmlentities with ENT_QUOTES | ENT_HTML5)
... and all methods from here

e.g.: data-filter="strip_tags(<p>)"

PS: the first argument will be the submitted value from the user

And also here you can combine some filters simply via "|" ...

e.g.: data-filter="strip_tags|trim|escape"

... and you can also add custom filters by your own.

$formValidator->addCustomFilter(
    'append_lall',
    function ($input) {
      return $input . 'lall';
    }
);

e.g.: data-filter="append_lall"

Unit Test

Composer is a prerequisite for running the tests.

composer install voku/HtmlFormValidator

The tests can be executed by running this command from the root directory:

./vendor/bin/phpunit

Support

For support and donations please visit Github | Issues | PayPal | Patreon.

For status updates and release announcements please visit Releases | Twitter | Patreon.

For professional support please contact me.

Thanks

Thanks to GitHub (Microsoft) for hosting the code and a good infrastructure including Issues-Managment, etc.
Thanks to IntelliJ as they make the best IDEs for PHP and they gave me an open source license for PhpStorm!
Thanks to Travis CI for being the most awesome, easiest continous integration tool out there!
Thanks to StyleCI for the simple but powerfull code style check.
Thanks to PHPStan && Psalm for relly great Static analysis tools and for discover bugs in the code!

voku / html-form-validator

Maintainers

Details