Nette Schema

In Schema 2.0, Type::$merge defaults to false. This means that if a partially supplied array is provided, the default values defined in the schema will not be merged into it; the array remains partial.

While mergeDefaults() is still available, it is deprecated and scheduled for removal in the next major version.

When combining multiple layers of data (e.g., via processMultiple), you can control how they merge using MergeMode.

Available modes:

• Replace: The new layer replaces the base layer entirely.
• OverwriteKeys: Merges by keys; numeric keys are overwritten positionally.
• AppendKeys: Merges by keys and appends new numeric elements.

Note on v1 compatibility: The magic key '_prevent_merging' has been removed. To achieve the same effect in v2, use mergeMode(MergeMode::Replace) or the NEON key!: syntax (if using Nette DI).

Errors in nette/schema are collected in a Context object and are never thrown mid-validation. This allows the engine to collect multiple errors before reporting them.

To prevent a validation step from running on data that has already failed a previous check, developers must use the $isOk() short-circuit pattern provided by Context::createChecker(). This ensures that later logic never attempts to validate or transform 'garbage' data rejected by earlier steps.

$isOk = $context->createChecker();
Helpers::validateType(...);
$isOk() && Helpers::validateRange(...);
$isOk() && ... && $value = $this->doTransform(...);

When calling castTo($type), the library uses Helpers::getCastStrategy to determine how to transform the input data into the target type. The behavior depends on the target $type:

• Built-in types: Uses standard PHP settype (e.g., casting to int, string, etc.).
• Classes with a constructor: The input array or stdClass is passed as named arguments to the constructor.
• Classes without a constructor: The input is converted to an object, and properties are assigned via property assignment (using Arrays::toObject).
• Enums: Note that Enums do not have constructors and fall into the new $type path, which will result in a PHP Error. Use specific enum handling if required.
• Scalars: If a scalar is passed to a class-based castTo, it is passed as a single argument to the constructor.

The Nette\Schema\Processor class is the main entry point. You provide a schema (defined via Expect) and the input data. The process() method returns normalized data (usually a stdClass object) or throws a Nette\Schema\ValidationException if validation fails.

To handle errors, catch ValidationException. You can retrieve error messages via $e->getMessages() or detailed Nette\Schema\Message objects via $e->getMessageObjects().

$processor = new Nette\Schema\Processor;

try {
	$normalized = $processor->process($schema, $data);
} catch (Nette\Schema\ValidationException $e) {
	echo 'Data is invalid: ' . $e->getMessage();
}

The methods before(), transform(), assert(), and castTo() are not independent stages but parts of a single pipeline.

1. before(): Runs during normalize() (pre-validation). Note that calling before() a second time will silently replace the first one.
2. transform() / assert() / castTo(): These all append to a single transformation list and execute in declaration order during the complete() phase, after type/range/pattern validation.

Because they run in order, the sequence matters: ->assert()->castTo() behaves differently than ->castTo()->assert().

The Schema object does not have a separate validate() phase. Instead, validation is integrated into the complete() step of the processing pipeline.

When using Processor::process(), the following sequence occurs:

1. normalize(): Data is normalized.
2. complete(): Data is validated (type checking, ranges, patterns, recursion) and transformed.
3. throwsErrors(): Errors are checked and thrown if present.

When using Processor::processMultiple(), the behavior changes slightly:

• before() hooks run for each individual dataset item during the normalization phase.
• transform(), assert(), and castTo() run once on the final, merged result during the single complete() phase.

This means before() sees individual configuration layers, while transform() sees the entire merged configuration.

There is a distinction between a type's default value and its nullability:

• A Type's default is null by default, but the type does not accept null unless nullable() is explicitly called.
• Array Coercion: If a type's default is an array, complete() will unconditionally turn a null value into an empty array []. This happens even if the type is marked nullable().
• Merging Defaults: In v2, defaults are no longer automatically merged into partially supplied arrays. To merge defaults into a partial array, you must explicitly use mergeDefaults().

The AnyOf element attempts to find a matching variant from a list of options.

• Selection Logic: It tries variants in the order they were declared. The first variant that matches both layers (using a 'throwaway' validation context) wins.
• Side Effects: Because matching happens in a throwaway context, any side effects or transformations performed by 'losing' variants are discarded.
• Error Reporting: If no variant matches, an aggregated error is produced (e.g., "expects to be A|B|C").

When a schema contains DynamicParameter (often used in Nette DI), the actual type validation is deferred.

During the complete() phase, the schema does not validate the real type of the dynamic parameter. Instead, it records the value, the expected type, and the path in the Context::dynamics collection. The actual validation is performed later by the consumer (like Nette DI) once the runtime parameters are known.

Install the library using Composer. It requires PHP 8.1 and supports up to PHP 8.5.

composer require nette/schema