Download the PHP package bus-factor/ares without Composer

Ares is a lightweight standalone validation library.

Table of Contents

• Installation
• Basic Usage
• Validation Errors
• Validation Options
  • allBlankable
  • allNullable
  • allRequired
  • allUnknownAllowed
• Validation Rules
  • allowed
  • blankable
  • datetime
  • directory
  • email
  • file
  • forbidden
  • length
  • max
  • maxlength
  • min
  • minlength
  • nullable
  • regex
  • required
  • schema
  • schema (list)
  • schema (map)
  • schema (tuple)
  • type
  • unknownAllowed
  • url
  • uuid
• Custom Types
• Custom Validation Error Messages
  • Change the Validation Error Message of a single Rule
  • Localization of Validation Error Messages
• Custom Validation Rules
• Sanitization
  • Sanitization Options

Installation

Install the library via composer:

Basic Usage

Validation Errors

The method returns if the provided data is valid, otherwise .

The method returns an object that holds a list of instances that are collected during the last data validation. The list of validation errors gets reset each time is called.

Each object implements the interface and contains details about the error.

The object is iterable but also offers 2 convenience methods:

• • returns an array of arrays that reflects the json:api spec
• • returns a nested array of error messages whose nested structure matches the input data's structure

Validation Options

Validation options may be passed on validation:

Default validation options are:

allBlankable

This option applies to the type only. If set , blank values are considered valid. If set , blank values are considered invalid.

This option may be overridden per field by using the rule:

allNullable

If set , is considered a valid value. If set , is not considered a valid value.

This option may be overridden per field by using the rule:

allRequired

If set (default) fields that are defined in the schema and not present in the input, are considered invalid. If set fields that are defined in the schema and not present in the input, are considered valid.

This option may be overridden per field by using the rule:

allUnknownAllowed

This option applies to the type only. If set fields that occur in the input data but are not defined in the schema are considered invalid. If set fields that occur in the input data but are not defined in the schema are considered valid.

Validation Rules

allowed

The validation rule checks if a value is in a given set of allowed values (enumeration).

Examples:

The validation rule is the opposite of the validation rule.

blankable

The rule applies to typed values only. If set , blank strings are considered valid. If set , blank strings are considered invalid (default).

Examples:

The validation rule may be used in combination with the validation option.

datetime

The validation rule applies to typed values only. If set , any parsable date/time string is considered valid. If set , date/time validation will not take place at all. If set a specific date/time format string, the given value will be checked against that format too. See DateTime::createFromFormat() for details about format strings.

Examples:

directory

The validation rule checks if the given string value contains the path to an existing directory. If set , only paths to existing directories are considered valid. If set , all input is considered valid (no validation).

Examples:

email

The validation rule checks if a value is a valid email address. If set , only valid email addresses are considered valid. If set , all input is considered valid (no validation).

Examples:

file

The validation rule checks if the given string value contains the path to an existing file. If set , only paths to existing files are considered valid. If set , all input is considered valid (no validation).

Examples:

forbidden

The validation rule checks if a value is in a given set of forbidden values (enumeration).

Examples:

The validation rule is the opposite of the validation rule.

length

The validation rule applies to and typed values. The validation rule checks if a string, or list has a specified exact length.

Examples:

max

The validation rule applies to and typed values only. The validation rule checks if a value is equal to or smaller a specified maximum value.

Examples:

Note this validation rule will throw a when used in conjunction with non-supported value types.

maxlength

The validation rule applies to and typed values. The validation rule checks if a string, or list does not exceed a specified maximum length.

Examples:

min

The validation rule applies to and typed values only. The validation rule checks if a value is equal to or greater a specified minimum value.

Examples:

Note this validation rule will throw a when used in conjunction with non-supported value types.

minlength

The validation rule applies to and typed values. The validation rule checks if a string, or list is not shorter than a specified minimum length.

Examples:

nullable

If set , is considered a valid value. If set , is considered an invalid value (default).

Examples:

The validation rule may be used in combination with the validation option.

regex

The validation rule applies to typed values only. The validation rule checks if a string matches a regular expression.

Examples:

required

Use the rule to enforce the presence of a value. If set , absent fields are considered invalid. If set , absent fields are considered valid (default).

Examples:

The validation rule may be used in combination with the validation option.

schema

The rule is mandatory when using type , , or .

schema (list)

The validator expects the schema to define a list item's validation rules.

Examples:

schema (map)

The validator expects the schema to define per field validation rules for associative array input.

Examples:

schema (tuple)

The validator expects the schema to define validation rules per input array element. During validation input array elements are expected to be continuous indexed starting from 0 (0, 1, 2, ...).

Examples:

Internally, all elements of a are required and cannot be declared optional by schema.

type

The rule is mandatory and defines the expected/allowed value type. Supported types are:

• numeric (float or integer)
• string
• map
• list
• tuple

Examples:

Read the section Custom Types to find out how to define and reuse your own types.

unknownAllowed

The unknownAllowed validation rule checks if a map contains fields that are not defined in the schema. If set true, fields that are not defined in the schema are considered valid. If set false, fields that are not defined in the schema are considered invalid.

Examples:

url

The url validation rule checks if a value is a valid URL.

Examples:

uuid

The uuid validation rule checks if a value is a valid UUID.

Examples:

Custom Types

Basically, a custom type is a user defined schema that is stored in and retrieved from a registry. Here's an example how it works:

Previously registered types are unregistered using TypeRegistry::unregister(). All priviously registered types are unregistered at once using TypeRegistry::unregisterAll(). It is also possible to define recursive types.

Custom Validation Error Messages

Change the Validation Error Message of a single Rule

The following example shows how validation error messages can be customized:

Just wrap your rule (key-value) into an array and add a 'message' key.

Localization of Validation Error Messages

All built-in validation rules use the Ares\Error\ErrorMessageRendererInterface to render the messages. If not specified, an instance of Ares\Error\ErrorMessageRenderer is created and passed to the validation process. If necessary, a custom error message renderer can be passed to the validator:

Custom Validation Rules

The following simple example shows how custom validation rules are implemented and integrated:

Sanitization

This following example shows how to sanitize data:

As shown in the example, by default sanitization makes these adjustments:

• Trim strings
• Convert numeric strings into integer, or string values
• Convert numeric non-empty strings into boolean values
• Removes unknown fields from the input data

Sanitization Options

trimStrings

If set true (default) sorrounding whitespace will be removed from strings. If set false sorrounding whitespace will be preserved.

purgeUnknown

If set true (default) unknown fields (fields/indices not defined in the schema) will be removed from the input data. If set false unknown fields will be preserved.