Gate¶

Verja\Gate validates structured data — associative arrays or objects with named properties. It is the main entry point for validating request bodies, form submissions, and similar payloads.

Required by default¶

A Gate requires its input to be a non-null structured value (array or object) unless 'nullable' is passed explicitly.

Scalar typed properties (->string(), ->int(), ->boolean(), ->number(), ->date(), ->any()) are optional by default — absent or empty values are simply skipped and not included in $result->data. Pass 'required' to enforce presence.

->array() and ->object() properties are required by default. Pass 'nullable' to make them optional.

$gate = (new Gate())
    ->string('name', 'required')   // explicitly required
    ->string('bio')                // optional, omitted from result->data if absent
    ->array('tags')                // required by default
    ->object('address', 'nullable', (new Gate())->string('city')); // optional

Typed property methods¶

These are the primary way to define properties. Each method creates a PropertyGate with an appropriate type filter or validator pre-applied:

Method	Type constraint	Notes
`->string(key, ...)`	value must be a string	no casting
`->int(key, ...)`	Integer filter applied	`"42"` → `42`
`->number(key, ...)`	Numeric filter applied	`"3.14"` → `3.14`
`->boolean(key, ...)`	Boolean filter applied	`"1"` / `"true"` → `true`
`->date(key, ...)`	DateTime filter applied	string → `\DateTime`
`->any(key, ...)`	no type constraint	accepts anything
`->array(key, ...)`	must be a list	see ArrayGate
`->object(key, GateInterface...)`	nested structured gate	see nested validation

Additional filters and validators are passed as further arguments:

$gate = (new Gate())
    ->string('username', 'required', 'strLen:3:20')
    ->string('email',    'required', 'emailAddress')
    ->int('age',         'between:0:150')
    ->boolean('active');

Filters and validators can be strings (parsed by name) or objects:

use Verja\Validator;
use Verja\Filter;

$gate = (new Gate())
    ->string('username', 'required', new Validator\StrLen(3, 20))
    ->string('email',    new Validator\Required(), new Validator\EmailAddress());

String definition format¶

String definitions use colon-separated parameters: 'className:param1:param2'. The class name is looked up in registered namespaces (case-insensitively, ucfirst). A ! prefix negates a validator by wrapping it in Validator\Not.

'strLen:3:20'     // StrLen(3, 20)
'between:1:100'   // Between(1, 100)
'!notEmpty'       // Not(NotEmpty)  — value must be empty

For parameters that contain colons or complex values, JSON array notation is supported:

'inArray:["foo","bar","baz"]'

Constructor shorthand¶

Pass an associative array as the only argument to define all properties at once:

$gate = new Gate([
    'username' => ['required', 'strLen:3:20'],
    'email'    => ['required', 'emailAddress'],
    'age'      => ['integer', 'between:0:150'],
]);

Nullable gate¶

By default a Gate fails if the input is null. Pass 'nullable' to allow it:

// 'address' block may be omitted entirely
$gate->object('address', 'nullable', (new Gate())
    ->string('street', 'required')
    ->string('city',   'required')
);

Additional properties¶

By default Gate ignores undeclared keys — they are not included in $result->data. Call ->additional() to let extra keys through, optionally with validation:

// Passthrough — any extra key is accepted and included in result->data as-is
$gate = (new Gate())
    ->string('type', 'required')
    ->additional();

// Validated — every extra key must satisfy the given constraints
$gate = (new Gate())
    ->string('type', 'required')
    ->additional('notEmpty', 'isString');

Errors from additional-property validation appear in errorMap under their own key.

Conditional required / nullable¶

'required' and 'nullable' on individual properties accept an optional condition — a string expression or callable — evaluated against the sibling fields at the same level. See Required & nullable for the full reference.

Immutable builder: requires / without / only¶

Gate provides immutable builder methods that return a cloned gate. Useful for deriving create vs. update variants from a shared base definition.

$base = (new Gate())
    ->string('name')
    ->string('email')
    ->string('role');

// Create: all three required
$createGate = $base->requires('name', 'email', 'role');

// Update: role cannot be changed, name and email optional
$updateGate = $base->without('role');

// Profile view: only name and email exposed
$profileGate = $base->only('name', 'email');

requires(string ...$keys) — marks the listed properties as required on the clone
without(string ...$keys) — removes the listed properties from the clone
only(string ...$keys) — keeps only the listed properties on the clone

Running validation¶

$result = $gate->validate($data);

if ($result->valid) {
    // $result->data contains filtered, validated values
    $user = new User($result->data);
} else {
    // $result->errors    — nested: ['field' => [Error, ...]]
    // $result->errorMap  — flat:   ['field' => [Error, ...], 'nested.field' => [...]]
}

See ValidationResult and errors for full details.

Convenience methods¶

// Returns bool without inspecting the result object
$gate->isValid($data);

// Throws InvalidValue on failure, returns filtered data on success
$gate->assertValid($data);

// Returns null on success, flat errorMap array on failure
$gate->errors($data);