README.md

SilverWare Validator

A form validation module for SilverStripe v4 which supports alternative client-side backends and customisable validation rules. Ships with Parsley.js as the default validation backend. Configured out-of-the-box for use with Bootstrap v4 forms.

Contents

• Requirements
• Installation
• Configuration
• Usage
• Rules
• Issues
• To-Do
• Contribution
• Attribution
• Maintainers
• License

Requirements

• SilverStripe Framework v4
• Bootstrap v4 (to use with default configuration)

Installation

Installation is via Composer:

$ composer require silverware/validator

Configuration

As with all SilverStripe modules, configuration is via YAML. The SilverStripe dependency injector is used to configure the validator backend. The module ships with a backend that uses Parsley.js:

SilverStripe\Core\Injector\Injector:
  ValidatorBackend:
    class: SilverWare\Validator\Backends\ParsleyBackend

The module has been designed to be as "backend agnostic" as possible. While Parsley.js is very powerful and should cater for most validation needs, you could certainly roll your own backend implementation and integrate it into the validator frontend using configuration.

Usage

To make use of the validator in your app, simply use the validator class in the header of your code:

use SilverWare\Validator\Validator;

You will also need to use the validator rule classes you wish to apply to your form, for example:

use SilverWare\Validator\Rules\LengthRule;
use SilverWare\Validator\Rules\PatternRule;
use SilverWare\Validator\Rules\RequiredRule;

Create a validator instance in your controller method that returns the Form, for example:

public function Form()
{
    $fields  = FieldList::create([
        ...
    ]);
    
    $actions = FieldList::create([
        ...
    ]);
    
    $validator = Validator::create();
    
    // define validator rules here!
    
    $form = Form::create($this, 'Form', $fields, $actions, $validator);
    
    return $form;
}

Now you can define your validator rules using the methods shown below.

Validator Rules

SilverWare Validator ships with many pre-built rules which you can use straight away to validate your forms. These rules support both client-side and server-side validation. Included with SilverWare Validator are the following rule classes:

• AlphaNumRule
• CheckRule
• ComparisonRule
• DateRule
• DigitsRule
• DomainRule
• EmailRule
• EqualToRule
• IntegerRule
• LengthRule
• MaxCheckRule
• MaxLengthRule
• MaxRule
• MaxWordsRule
• MinCheckRule
• MinLengthRule
• MinRule
• MinWordsRule
• NotEqualToRule
• NumberRule
• PatternRule
• RangeRule
• RemoteRule
• RequiredRule
• URLRule
• WordsRule

Each of these rules will be covered in greater detail below.

Setting Rules

To set a rule for a particular form field, use the setRule method, and pass the field name and the rule instance. For example:

$validator->setRule(
    'MyFieldName',
    LengthRule::create(10, 20) // this field's value must be 10-20 characters in length
);

To set more than one rule for a field, you can use the setRules method and pass an array of rule instances:

$validator->setRules(
    'MyDomainName',
    [
        RequiredRule::create(),  // this field is required
        DomainRule::create()     // this field must be a valid domain name
    ]
);

Required Fields

Since fields are often required for almost any form, shortcut methods have been provided to define required fields. Use addRequiredField with the field name and optional custom message parameter:

$validator->addRequiredField('MyRequiredField');
$validator->addRequiredField('MyOtherRequiredField', 'Dis field be mandatory, yo!');

To add required fields in bulk, use addRequiredFields with an array of field names:

$validator->addRequiredFields([
    'ThisFieldIsRequired',
    'SoIsThisField',
    'AndThisField'
]);

Custom Messages

All rule classes come with a default message which is shown to the user when the rule validation fails. You can define your own custom messages by using the setMessage method on a rule, for example:

$validator->setRule(
    'MyAge',
    MaxRule::create(130)->setMessage(
        'I find it hard to believe you are over 130 years old!'
    )
)

Disabling Validation

By default, SilverWare Validator performs both client-side and server-side validation. While it's recommended to leave both methods of validation enabled, if you need to disable either, you can use the following methods:

$validator->setClientSide(false);  // disables client-side validation
$validator->setServerSide(false);  // disables server-side validation

Trigger Events

The out-of-the-box validator Parsley.js is set to trigger form validation upon field change by default. You can customise when you'd like validation to be triggered by using the setTriggerOn method on the backend, for example:

$validator->getBackend()->setTriggerOn([
    'focusin',
    'focusout'
]);

You can also simply pass the trigger events as a string:

$validator->getBackend()->setTriggerOn('focusin focusout');

Parsley.js supports triggering by any of the standard jQuery events.

Rules

AlphaNumRule

use SilverWare\Validator\Rules\AlphaNumRule;

Tests that the value is an alphanumeric string, containing only basic letters, numbers, and the underscore character.

$validator->setRule(
    'MyFieldName',
    AlphaNumRule::create()
);

CheckRule

use SilverWare\Validator\Rules\CheckRule;

Used for a OptionsetField such as CheckboxSetField. Ensures that the user chooses a certain number of options, between the given $min and $max parameters.

$validator->setRule(
    'MyCheckboxSet',
    CheckRule::create(2, 4)  // user must select between 2 and 4 options
);

ComparisonRule

use SilverWare\Validator\Rules\ComparisonRule;

Compares the value of one field to another, using the specified comparison type:

• ComparisonRule::LESS_THAN
• ComparisonRule::LESS_THAN_OR_EQUAL
• ComparisonRule::GREATER_THAN
• ComparisonRule::GREATER_THAN_OR_EQUAL

$validator->setRule(
    'MyLesserValue',
    ComparisonRule::create(
        ComparisonRule::GREATER_THAN,
        'MyGreaterValue'
    )
);

DateRule

use SilverWare\Validator\Rules\DateRule;

Ensures that the entered value is a date of the specified format. The rule constructor supports two arguments. The first is the required date format using the client-side Moment.js specification.

The optional second argument specifies the server-side PHP date format, however the rule will convert the client-side format appropriately if you omit the second argument.

$validator->setRule(
    'MyDateField',
    DateRule::create('YYYY-MM-DD')  // ensures an ISO standard date, e.g. 2017-05-12
);

DigitsRule

use SilverWare\Validator\Rules\DigitsRule;

Ensures only digits are entered, i.e. the numbers 0-9 only.

$validator->setRule(
    'MyDigitsField',
    DigitsRule::create()
);

DomainRule

use SilverWare\Validator\Rules\DomainRule;

Tests that the entered value is a valid domain name. Supports the new TLD domains and also localhost.

$validator->setRule(
    'MyDomainName',
    DomainRule::create()
);

EmailRule

use SilverWare\Validator\Rules\EmailRule;

Ensures that the value is a valid email address.

$validator->setRule(
    'MyEmailField',
    EmailRule::create()
);

EqualToRule

use SilverWare\Validator\Rules\EqualToRule;

Ensures that the value of one field is equal to the value of another.

$validator->setRule(
    'MyFirstValue',
    EqualToRule::create('MySecondValue')
);

IntegerRule

use SilverWare\Validator\Rules\IntegerRule;

Tests that the entered value is a valid positive or negative integer.

$validator->setRule(
    'MyIntField',
    IntegerRule::create()
);

LengthRule

use SilverWare\Validator\Rules\LengthRule;

Ensures that the length of the entered value is between the specified $min and $max range.

$validator->setRule(
    'MyFieldName',
    LengthRule::create(20, 40)  // value must be between 20-40 characters in length
);

MaxCheckRule

use SilverWare\Validator\Rules\MaxCheckRule;

Used for a OptionsetField such as CheckboxSetField. Specifies that the user may only select a maximum number of options.

$validator->setRule(
    'MyCheckboxSet',
    MaxCheckRule::create(4)  // user can select a maximum of 4 options
);

MaxLengthRule

use SilverWare\Validator\Rules\MaxLengthRule;

Ensures that the entered value is of a maximum length.

$validator->setRule(
    'MyFieldName',
    MaxLengthRule::create(40)  // value must be 40 characters in length or less
);

MaxRule

use SilverWare\Validator\Rules\MaxRule;

Tests that a numeric value is less than or equal to the specified amount.

$validator->setRule(
    'MyNumberField',
    MaxRule::create(255)  // number value must be 255 or less
);

MaxWordsRule

use SilverWare\Validator\Rules\MaxWordsRule;

Ensures that the value is of the specified number of words or less.

$validator->setRule(
    'MyTextArea',
    MaxWordsRule::create(50) // value must be 50 words or less
);

MinCheckRule

use SilverWare\Validator\Rules\MinCheckRule;

Used for a OptionsetField such as CheckboxSetField. Ensures that the user selects a minimum number of options.

$validator->setRule(
    'MyCheckboxSet',
    MinCheckRule::create(2)  // user must select at least 2 options
);

MinLengthRule

use SilverWare\Validator\Rules\MinLengthRule;

Ensures that the entered value is of a minimum length.

$validator->setRule(
    'MyFieldName',
    MinLengthRule::create(20)  // value must be at least 20 characters in length
);

MinRule

use SilverWare\Validator\Rules\MinRule;

Tests that the numeric value is greater than or equal to the specified amount.

$validator->setRule(
    'MyNumberField',
    MinRule::create(42)  // the entered value must be 42 or greater
);

MinWordsRule

use SilverWare\Validator\Rules\MinWordsRule;

Ensures that the entered value is of the specified number of words or greater.

$validator->setRule(
    'MyTextArea',
    MinWordsRule::create(20)  // value must contain at least 20 words
);

NotEqualToRule

use SilverWare\Validator\Rules\NotEqualToRule;

Ensures that the value of one field is NOT equal to the value of another.

$validator->setRule(
    'MyFirstValue',
    NotEqualToRule::create('MySecondValue')
);

NumberRule

use SilverWare\Validator\Rules\NumberRule;

Tests that the entered value is numeric, i.e. an integer or a floating-point number.

$validator->setRule(
    'MyNumericValue',
    NumberRule::create()  // value must be numeric
);

PatternRule

use SilverWare\Validator\Rules\PatternRule;

Uses a regular expression to test the entered value. Ensure that the format of your regular expression works in both JavaScript, and also PHP preg_match so that both client and server validation functions correctly.

$validator->setRule(
    'MyFieldName',
    PatternRule::create('/ware$/')  // ensures the entered string ends with 'ware'
);

RangeRule

use SilverWare\Validator\Rules\RangeRule;

Specifies a number range that the entered value must be between.

$validator->setRule(
    'MyNumericValue',
    RangeRule::create(1, 5)  // value must be between 1 and 5
);

RemoteRule

use SilverWare\Validator\Rules\RemoteRule;

Tests the value on the client-side using an Ajax request, and uses Guzzle to test the value when submitted to the server.

The following arguments are permitted for the rule constructor:

$rule = RemoteRule::create(
    $url,  // url to call
    $params,  // request parameters, e.g. ['myVar' => 123]
    $options, // options for request, e.g. ['type' => 'POST']
    $remoteValidator  // remote validator to use, 'default' or 'reverse'
);

For example, you might use the RemoteRule to check if a username is available:

$validator->setRule(
    'MyUserName',
    RemoteRule::create(
        $this->Link('checkusername')  // controller method
    )->setMessage('That username is unavailable')
);

The server will receive the name of the field and it's value as parameters, i.e. ?MyUserName=sallybloggs. By default, if the RemoteRule receives an HTTP status code of between 200-299, it is considered to be valid. Anything else will return an invalid result.

If you'd like to reverse this behavior, i.e. 200-299 is considered to be invalid, you can use "reverse" mode:

$validator->setRule(
    'MyUserName',
    RemoteRule::create(
        $this->Link('checkusername')
    )->setRemoteValidator('reverse')
);

For more information on using remote validation, see the Parsley.js documentation.

RequiredRule

use SilverWare\Validator\Rules\RequiredRule;

Defines the specified field as a required (mandatory) field that must be completed by the user.

$validator->setRule(
    'MyRequiredField',
    RequiredRule::create()
);

URLRule

use SilverWare\Validator\Rules\URLRule;

Ensures that the entered value is a valid URL.

$validator->setRule(
    'MyURL',
    URLRule::create()
);

WordsRule

use SilverWare\Validator\Rules\WordsRule;

Ensures that the entered value is between $min and $max words.

$validator->setRule(
    'MyTextArea',
    WordsRule::create(10, 25)  // user must enter between 10 and 25 words
);

Issues

Please use the GitHub issue tracker for bug reports and feature requests.

To-Do

• Tests

Contribution

Your contributions are gladly welcomed to help make this project better. Please see contributing for more information.

Attribution

• Makes use of Parsley.js by Guillaume Potier.
• Makes use of Moment.js by Iskren Ivov Chernev and others.
• Makes use of Guzzle by Michael Dowling and others.
• Makes use of Bootstrap by the Bootstrap Authors and Twitter, Inc.
• Inspired by SilverStripe ZenValidator by Shea Dawson.

Maintainers

Colin Tucker	Praxis Interactive

License

BSD-3-Clause © Praxis Interactive