Spec.md

Validate\Spec

A Spec object encapsulates a Validation object as well as some extra attributes. See the constructor documentation for all the possible parameters. The Spec class is rarely used stand-alone since it is only able to validate a single value.

• Class name: Spec
• Namespace: Validate

SYNOPSIS

// Typical creation:
$spec = new Validate\Spec(array(
	'optional'		=> true,
	'description'	=> 'Just an optional description',
	'validation'	=> (new Validate\Validation(array(
		'max_length'	=> 10,
		'regex'			=> '/a/',
		'callbacks'		=> array(
			'is_lc'	=> function($s) { return strtolower($s) == $s; },
		),
	))),
));

// Lazy creation:
$spec = new Validate\Spec(array(
	'optional'		=> true,
	'description'	=> 'Just an optional description',
	'validation'	=> array(
		'max_length'	=> 10,
		'regex'			=> '/a/',
		'callbacks'		=> array(
			'is_lc'	=> function($s) { return strtolower($s) == $s; },
		),
	),
));

// Very lazy creation (Validation options instead of a "validation" key):
$spec = new Validate\Spec(array(
	'optional'		=> true,
	'description'	=> 'Just an optional description',
	'max_length'	=> 10,
	'regex'			=> '/a/',
	'callbacks'		=> array(
		'is_lc'	=> function($s) { return strtolower($s) == $s; },
	),
));

// And finally validating something:
print (int) $spec->validate("hay") . "\n";

Methods

__construct

__construct(array $args)

Constructor.

The following options are supported:

Key	Description
allow_empty	boolean, allow empty strings to be validated and pass 'optional' check
before	Callback that takes a reference to the value as argument so that it can mutate it before validation. It may trigger validation failure by returning boolean false.
after	Callback that takes a reference to the value as argument so that it can mutate it after validation. It may trigger validation failure by returning boolean false.
default	Any non-null value (even closures!); null arguments to validate() are replaced with this (or it's result in if it's a closure).
optional	boolean, if true, then null values are allowed
description	Optional description used in exception messages
validation	Validation object

For convenience sake, if unknown arguments are passed and no "validation" option is given, then the Validation object is created using those arguments.

__get

mixed __get($key)

Don't call this. This PHP magic method provides public readonly access to protected properties. All options passed into the constructor can be read using property accessors, e.g. print $spec->optional . "\n";

allow_empty

boolean allow_empty()

Returns the value of the 'allow_empty' option as passed into the constructor.

getDefault

string|null getDefault()

Returns the value of the 'default' option as passed into the constructor.

description

string|null description()

Returns the value of the 'description' option as passed into the constructor.

before

boolean before()

Returns the value of the 'before' option as passed in the constructor.

after

boolean after()

Returns the value of the 'after' option as passed in the constructor.

optional

boolean optional()

Returns the value of the 'optional' option as passed into the constructor.

validation

Validation|null validation()

Return the value of the 'validation' option as passed into or created by the constructor.

getLastFailure

string|null getLastFailure()

Return the name of the check that the last validation failed on.

validate

boolean validate(mixed &$arg)

Validates the given argument reference. If 'before' or 'after' callback options were passed into the constructor, then these are applied to the argument in order to modify it in place, which is why it is passed by reference.

validate_ex

void validate_ex(mixed &$arg)

This simply wraps the validate() method in order to throw a ValidationCheckException on failure instead of returning a boolean.