Download the PHP package silverware/validator without Composer

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:

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:

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:

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

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

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:

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

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:

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

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:

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:

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:

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

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

Rules

AlphaNumRule

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

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.

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

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.

DigitsRule

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

DomainRule

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

EmailRule

Ensures that the value is a valid email address.

EqualToRule

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

IntegerRule

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

LengthRule

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

MaxCheckRule

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

MaxLengthRule

Ensures that the entered value is of a maximum length.

MaxRule

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

MaxWordsRule

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

MinCheckRule

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

MinLengthRule

Ensures that the entered value is of a minimum length.

MinRule

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

MinWordsRule

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

NotEqualToRule

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

NumberRule

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

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.

RangeRule

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

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:

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

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:

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

RequiredRule

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

URLRule

Ensures that the entered value is a valid URL.

WordsRule

Ensures that the entered value is between $min and $max 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