Download the PHP package smwcentral/validator without Composer

SMW Central Validator

The lightweight form validation component used by SMW Central. Aims to provide a friendly and flexible API at a minimal runtime cost.

• Installation
• Example
• Usage
  • Basic usage
  • Shorthand types
  • Bailing
  • Message bags
  • Manual validation
  • CSRF tokens
  • Messages
  • Shorthand configuration
• Tests
• License
• Credits

Installation

Install with Composer. Requires PHP 7.3+ with the JSON and mbstring extensions.

Example

Usage

Basic usage

Construct a Validator, passing it an array of fields that may be validated, usually just $_POST.

Use retrieve() to create a Variable object that represents a given field. By default, fields are required and will create a validation error if no value exists. Pass a second argument to specify a default value.

The first validation rule called on each Variable must specify the data type. All other validation rules will throw a LogicException until the type is specified.

The field's value is coerced to its given data type. A validation error is added if this isn't possible.

After specifying a data type, call other validation rules as appropriate. All methods on the Variable can be chained.

Validation rules that deal with the "size" of the value use the number itself for integers and floats or the length of strings and arrays.

Finally, use value() to get the value of the field. It's guaranteed to be whichever data type the Variable was specified to use (or null if the field is optional). None of the other validation rules are necessarily met until you check the result of the validation.

Use the passes() method on the Validator to check if all validation rules have succeeded. Use errors() to get a MessageBag with errors for each field.

Shorthand types

The Validator has shorthand methods that retrieve a variable and set its data type at once. You will practically always use these instead of retrieve().

A complete chain usually looks like this:

Bailing

By default, all validation rules called on a Variable will run. In the end, there may be multiple validation errors. Use the bail() method to ignore validation rules for a Variable after the first failure.

Message bags

Validation errors are collected in a MessageBag that can be accessed with the errors() method of a Validator. MessageBags hold any number of Message objects for any number of fields.

Manual validation

Variables only provide basic validation rules. You will often need to validate the data further. Retrieve the type-casted field value with value(), then run any logic you need. Add your own validation errors with the add() method of the MessageBag.

For finer control over the validation error (e.g. to provide extra arguments), you can also pass an instance of Message to errors()->add().

CSRF tokens

The passes() method of the Validator can automatically check a CSRF token. To enable this functionality, set Validator::$tokenProvider to an instance of a custom class that implements the ITokenProvider interface.

You can use passes(false) to skip token validation if a token provider is a configured.

Messages

Validation errors are represented by Message objects.

Internally, messages only contain a key that is later passed to a message resolver to construct a human-friendly message. This package includes a rudimentary default resolver.

In most cases, you'll want to use your own resolver. Set Message::$resolver to an instance of a custom class that implements the IMessageResolver interface. Check the getMessages() method in src/DefaultMessageResolver.php for a list of message keys that the validator will use.

Note that Messages maintain their own copy of the field name, not necessarily identical to the field name that owns the Message in the MessageBag.

The $args array passed to resolveMessage() contains a set of arbitrary additional arguments. Some validation rules will give such arguments to their messages. For example, the between() rule will add min and max arguments. You can also provide custom arguments to any Variable using the third parameter of the Validator's retrieve() method and its shorthands.

When adding validation errors manually, you can create a Message yourself to provide arguments.

The default message resolver will directly include the field's name in the message. To ensure a coherent message is created, you can pass an argument named field to override the name:

Of course, it is up to you to implement such logic in a custom message resolver.

Shorthand configuration

You can use Validator::configure() to set a message resolver and a token provider at once.

If null is passed as one of the arguments, it will be ignored.

Tests

Tests are in the tests directory and use PHPUnit. Run with vendor/bin/phpunit tests.

License

Released under the MIT License.

Credits

Built and maintained by Telinc1. SMW Central is property of Noivern.