Download the PHP package icanboogie/validate without Composer

Validate

The icanboogie/validate package offers a simple API to validate data.

The following validators are available:

• Flags

  • Required, required: States that a value is required. Should be specified first.

• Generic

  • Blank, blank: Validates that a value is blank.
  • NotBlank, not-blank: Validates that a value is blank.

• Type comparison

  • Boolean, boolean: Validates that a value is a boolean.
  • IsFalse, is-false: Validates that a value is false.
  • IsNull, is-null: Validates that a value is null.
  • NotNull, not-null: Validates that a value is not null.
  • IsTrue, is-true: Validates that a value is true.
  • Type, type: Validates that a value is of a specified type.

• Reference comparison

  • Equal, equal: Validates that two values are equal.
  • NotEqual, not-equal: Validates that two values are not equal.
  • Identical, identical: Validates that two values are identical.
  • NotIdentical, not-identical: Validates that two values are not identical.
  • Max, max: Validates that a value has a maximum value.
  • MaxLength, max-length: Validates that a value has a maximum length.
  • Min, min: Validates that a value has a minimum value.
  • MinLength, min-length: Validates that a value has a minimum length.

• Range comparison

  • Between, between: Validates that a value is between two references.
  • NotBetween, not-between: Validates that a value is not between two references.
  • BetweenLength, between-length: Validates that a string length is between two references.
  • NotBetweenLength, not-between-length: Validates that a string length is not between two references.

• String comparison

  • Email, email: Validates that a value is a valid email.
  • JSON, json: Validates that a value is a valid JSON.
  • Regex, regex: Validates that a value matches or not a pattern.
  • TimeZone, timezone: Validates that a value is a valid time zone.
  • URL, url: Validates that a value is a valid URL.

The following example demonstrates how data may be validated:

Validation

A validation is defined using an array of key/value pairs where key is an attribute to validate and key is the rules. Rules may be defined as a string or an array of key/value pairs where key is a validator class, or alias, and value an array of parameters and options. Optionally you may provide a validator provider, if you don't, an instance of BuiltinValidatorProvider is created by default.

A validation is represented by a Validation instance.

Empty values, required attributes

It is important to know that validators are not run on empty values, unless the required validator is used too. The following values are considered empty: null, an empty array, an empty trimmed string; but false and 0 are considered valid values.

The following example demonstrates how required influences validation:

Validating data

The validate() method validates data. It returns a ValidationErrors instance if the validation failed, an empty array otherwise.

Asserting that data is valid

The assert() method may be used to assert that data is valid. Instead of returning a ValidationErrors instance like validate(), the method throws a ValidationFailed exception. The validation errors may be retrieved from the exception using its errors property.

Special validation options

The following validation options may be defined:

• ValidatorOptions::OPTION_MESSAGE: A custom error message, which overrides the validator default message.

• ValidatorOptions::OPTION_IF: The validator is used only if the callable defined by this option returns true. The callable may be a closure or an instance implementing the IfCallable interface.

• ValidatorOptions::OPTION_UNLESS: The validator is skipped if the callable defined by this option returns true. The callable may be a closure or an instance implementing the UnlessCallable interface.

• ValidatorOptions::OPTION_STOP_ON_ERROR: If true, the validation of a value stops after an error. This option is always true for the Required validator.

Validation context

The validation context is represented by a Context instance and is passed along with the value to validate to the validator. The validator may used the context to retrieve parameters and options, and when required get a complete picture of the ongoing validation.

The following properties are available:

• attribute: The attribute being validated.
• value: The value of the attribute being validated.
• validator: The current validator.
• validator_params: The parameters and options for the current validator.
• reader: A Reader adapter giving access to the values being validated.
• message: The possible error message for the current validator.
• message_args: The arguments for the possible error message.
• errors: The collected errors.

The following example demonstrates how a validator may retrieve its parameters and options from the context, and a value from the value reader:

Validator provider

Validator instances are obtained using a validator provider. By default, an instance of BuiltinValidatorProvider is used, but you can provide your own provider, or better, a provider collection.

The following example demonstrates how to use the builtin provider:

The following example demonstrates how to provide your own sample validator:

The following example demonstrates how to provide validators using a container:

The following example demonstrates how to use a number of providers as a collection:

Requirements

The package requires PHP 5.5 or later.

Installation

The recommended way to install this package is through Composer:

$ composer require icanboogie/validate

Cloning the repository

The package is available on GitHub, its repository can be cloned with the following command line:

$ git clone https://github.com/ICanBoogie/validate.git

Documentation

The package is documented as part of the ICanBoogie framework documentation. You can generate the documentation for the package and its dependencies with the make doc command. The documentation is generated in the build/docs directory. ApiGen is required. The directory can later be cleaned with the make clean command.

Testing

The test suite is ran with the make test command. PHPUnit and Composer need to be globally available to run the suite. The command installs dependencies as required. The make test-coverage command runs test suite and also creates an HTML coverage report in build/coverage. The directory can later be cleaned with the make clean command.

The package is continuously tested by Travis CI.

License

icanboogie/validate is licensed under the New BSD License - See the LICENSE file for details.