phpgt / domvalidation
Server side form validation using web standards.
Fund package maintenance!
PhpGt
Requires
- php: >=8.1
- phpgt/cssxpath: 1.*
- phpgt/dom: ^4.1
Requires (Dev)
- phpmd/phpmd: ^2.13
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^10.0
- squizlabs/php_codesniffer: ^3.7
README
HTML forms can be annotated in such a way that the individual input elements can describe their own validation rules. The simplest annotation is the required
attribute, which can be specified on input elements to indicate that the form is not to be submitted until a value is given.
This repository performs W3C form validation for projects that have a server-side DOM, such as within WebEngine applications.
Example usage
<form id="example-form" method="post"> <label> <span>Your name</span> <input name="name" required /> </label> <label> <span>Your email</span> <input name="email" type="email" required /> </label> <label> <span>Your account ID</span> <input name="account" pattern="\S*\d{,3}" /> </label> <label> <span>Your nation</span> <select name="nation" required> <option></option> <option>Oceania</option> <option>Eurasia</option> <option>Eastasia</option> </select> </label> <button>Submit</button> </form>
The above HTML will be validated on the client as usual, but using the PHP below will also provide server-side validation without any additional validation logic to be written.
Validation rules present in the above HTML form:
name
input is required to be not empty.email
input is required to be not empty, and must be a valid email address.account
input is not required, but when a value is submitted, it must match the provided regular expression (any number of non-whitespace characters followed by up to 3 numbers).nation
input must be one of the three enumerations present in the<select>
element.
use Gt\Dom\HTMLDocument; use Gt\DomValidation\Validator; use Gt\DomValidation\ValidationException; // Assume this function is triggered when POST data arrives. function handleSubmit($inputData) { $document = new HTMLDocument(file_get_contents("example-form.html")); // First, obtain a reference to the form we wish to validate. $form = $document->querySelector("#example-form"); $validator = new Validator(); try { // Within a try/catch, pass the form and the user input into the Validator. $validator->validate($form, $inputData); } catch(ValidationException) { // If there are any validation errors, we can iterate over them to display // to the page, and return early as to not action the user input. foreach($validator->getLastErrorList() as $name => $message) { // Here we can add an attribute to the parent of the input, for displaying // the error message using CSS, for example. $errorElement = $form->querySelector("[name=$name]"); $errorElement->parentNode->dataset->validationError = $message; } // Return early so user input isn't used when there are validation errors. return; } // Finally, if the input contains no validation errors, continue as usual. sendInputToDatabase($inputData); }
Supported validation mechanisms:
It's possible to add your own validation mechanism by extending the FormValidator
class and overriding the necessary functions.
required
- field can not be left blankpattern
- must match the provided regular expressiontype
- must match the provided inbuilt data typemin
- for numerical inputs, the minimum allowed valuemax
- for numerical inputs, the maximum allowed valueminlength
- the minimum number of characters allowedmaxlength
- the maximum number of characters allowedstep
- the granularity that is required
Supported types:
tel
url
email
date
month
week
time
datetime-local
number
range
Special element behaviour
When using <select>
and <input type="radio" />
elements, their contained options are used as validation enumerations, meaning that values that are not part of the contained options will throw validation errors.