Nette Schema

https://github.com/nette/schema
Admin
A practical library for validation and normalization of data structures against a given schema with...
Tokens:117,370
Snippets:830
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### firstIsDefault() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/AnyOf.md

Example of using firstIsDefault() to set the default value to 'hello'.

```php
$schema = Expect::anyOf(Expect::string('hello'), true, null)->firstIsDefault();
// default is 'hello'
```

--------------------------------

### process() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Processor.md

Example of using process() to normalize and validate a structure with boolean and integer fields.

```php
$processor = new Nette\Schema\Processor;
$schema = Expect::structure([
	'processRefund' => Expect::bool(),
	'refundAmount' => Expect::int(),
]);

$normalized = $processor->process($schema, [
	'processRefund' => true,
	'refundAmount' => 17,
]);
```

--------------------------------

### Deprecated method usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/AnyOf.md

Example of calling min() on an anyOf() schema, which throws Nette\DeprecatedException.

```php
Expect::anyOf(1, 2)->min(1); // throws Nette\DeprecatedException: min() is not available on anyOf()
```

--------------------------------

### mergeMode() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Structure.md

Example of using mergeMode() with MergeMode::Replace.

```php
Expect::structure([...])->mergeMode(MergeMode::Replace);
```

--------------------------------

### description() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Base.md

Creates a string schema with a description for the JSON Schema export.

```php
$schema = Expect::string('localhost')->description('Database server hostname');
```

--------------------------------

### process() error handling example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Processor.md

Example of catching ValidationException when processing invalid data. Shows how to access error messages.

```php
try {
	$normalized = $processor->process($schema, ['refundAmount' => 'nope']);
} catch (Nette\Schema\ValidationException $e) {
	echo $e->getMessage();       // The item 'refundAmount' expects to be int, 'nope' given.
	echo $e->getMessages();      // list of all messages as strings
	echo $e->getMessageObjects(); // list of Nette\Schema\Message
}
```

--------------------------------

### Expect magic method usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Shows how to call magic methods with positional or named defaults, and how to combine listOf with a default string.

```php
$schema = Expect::int(10);            // default 10
$schema = Expect::bool(default: true); // named default
$schema = Expect::listOf(Expect::string(default: 'a'));
```

--------------------------------

### assert() usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Base.md

Two usage examples for assert(): one with a closure and description, and one with a string handler name. On failure, a Message::FailedAssertion error is added and null returned.

```php
$schema = Expect::arrayOf('string')
	->assert(fn($v) => count($v) % 2 === 0, 'Even items in array');
$schema = Expect::string()->assert('is_file'); // string handler name
```

--------------------------------

### createChecker() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Context.md

Example of using createChecker() to control the flow of validation steps. Each step runs only while the previous steps stayed clean. If any step adds an error, the checker returns false and the process stops.

```php
$isOk = $context->createChecker();
$value = $this->validate($value, $context);   // may add errors
$isOk() && $value !== null && $value = $this->mergeDefault($value);
$isOk() && $value = $this->doTransform($value, $context);
if (!$isOk()) {
	return null;
}
```

--------------------------------

### extend() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/TupleType.md

Example showing how to extend a tuple with additional position schemas.

```php
$base = Expect::tuple([Expect::int(), Expect::string()]);
$extended = $base->extend([Expect::bool()]);
```

--------------------------------

### Run PHPStan static analysis

Source: https://github.com/nette/schema/blob/master/AGENTS.md

Runs PHPStan at level 8 via Composer script. Ensures static analysis passes.

```bash
composer phpstan
```

--------------------------------

### skipDefaults() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Processor.md

Example of using skipDefaults() to prevent filling missing properties with defaults. The output is an empty stdClass.

```php
$processor = new Processor;
$processor->skipDefaults();

$normalized = $processor->process(
	Expect::structure(['a' => Expect::int(1)]),
	[],
); // => stdClass { }  — 'a' is not filled with 1
```

--------------------------------

### Helpers::formatValue() usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Helpers.md

Demonstrates output for a long string (truncated to 15 chars) and an object.

```php
Helpers::formatValue('hello world, this is long'); // => 'hello world, thi...'
Helpers::formatValue(new stdClass);                 // => 'object stdClass'
```

--------------------------------

### extend() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Structure.md

Example of extending a structure with additional properties. Later properties override earlier ones of the same name.

```php
$dog = Expect::structure(['name' => Expect::string(), 'age' => Expect::int()]);
$dogWithBreed = $dog->extend(['breed' => Expect::string()]);
```

--------------------------------

### mergeMode() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/ArrayType.md

Example of using mergeMode() with MergeMode::Replace to replace the earlier array wholesale.

```php
use Nette\Schema\MergeMode;

Expect::arrayOf('string')->mergeMode(MergeMode::Replace);
```

--------------------------------

### Expect::arrayOf() usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Three usage examples for Expect::arrayOf(): values as strings, values strings with int keys, and values as booleans.

```php
$schema = Expect::arrayOf('string');               // values are strings
```

```php
$schema = Expect::arrayOf('string', 'int');        // values strings, keys ints
```

```php
$schema = Expect::arrayOf(Expect::bool());         // values booleans
```

--------------------------------

### default() usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Base.md

Shows setting a default with the explicit method and the shorthand form via Expect::int(10). The shorthand is equivalent to ->default(10).

```php
$schema = Expect::bool()->default(false);
$schema = Expect::int(10); // shorthand for ->default(10)
```

--------------------------------

### Merge multiple configurations with processMultiple()

Source: https://github.com/nette/schema/blob/master/readme.md

Demonstrates merging several datasets in order, with later ones taking precedence. The example merges defaults and user config, validating the final result as a whole.

```php
$schema = Expect::structure([
	'host' => Expect::string(),
	'port' => Expect::int(),
	'logging' => Expect::bool(),
]);

$defaults = ['host' => 'localhost', 'port' => 3306, 'logging' => false];
$userConfig = ['port' => 5432, 'logging' => true];

$config = $processor->processMultiple($schema, [$defaults, $userConfig]);
// $config = {'host' => 'localhost', 'port' => 5432, 'logging' => true}
```

--------------------------------

### Usage example with Processor

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/StringType.md

Shows basic usage with min/max bounds and error handling for format and pattern. The first process returns 'hello', the second throws a length out of range exception. The try-catch demonstrates a validation error message.

```php
$processor = new Nette\Schema\Processor;

// basic
$schema = Expect::string()->min(3)->max(20);
$processor->process($schema, 'hello'); // => 'hello'
$processor->process($schema, 'ab');    // throws: length out of range 3..20

// format, pattern, error handling
try {
	$processor->process(Expect::type('email')->pattern('\w+\.\w+@.*'), 'nope');
} catch (Nette\Schema\ValidationException $e) {
	echo $e->getMessage(); // The item expects to be email, 'nope' given.
}
```

--------------------------------

### Expect::array() usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Two usage examples for Expect::array(): one for a plain array with default [], and one for a structure-like array with required and optional string elements.

```php
$schema = Expect::array();                    // any array, default []
```

```php
$schema = Expect::array([                     // structure-like array output
	'required' => Expect::string()->required(),
	'optional' => Expect::string(),
]);
```

--------------------------------

### Install Nette Schema via Composer

Source: https://github.com/nette/schema/blob/master/readme.md

Install the library using Composer. Requires PHP 8.1 and supports up to PHP 8.6.

```shell
composer require nette/schema
```

--------------------------------

### Run a specific structure test

Source: https://github.com/nette/schema/blob/master/AGENTS.md

Runs a single test file for the Expect structure. Useful for focused debugging.

```bash
vendor/bin/tester tests/Schema/Expect.structure.phpt -s
```

--------------------------------

### Expect::anyOf() usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Shows two ways to use anyOf: with a list and with firstIsDefault(). A null in the set always wins over variants that would coerce null.

```php
$schema = Expect::listOf(Expect::anyOf('a', true, null));
```

```php
$schema = Expect::anyOf(Expect::string('hello'), true, null)->firstIsDefault();
```

--------------------------------

### pattern() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/StringType.md

Creates a schema that matches exactly 9 digits.

```php
$schema = Expect::string()->pattern('\d{9}'); // exactly 9 digits
```

--------------------------------

### Run all tests with vendor/bin/tester

Source: https://github.com/nette/schema/blob/master/AGENTS.md

Runs the full test suite for the Schema package. The -s flag shows output. An alternative is `composer tester`.

```bash
vendor/bin/tester tests/Schema/ -s        # or: composer tester
```

--------------------------------

### Setting length bounds with min() and max()

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/StringType.md

Shows how to set only one bound or both. The first example limits to at most 20 bytes, the second to 1..5 characters.

```php
Expect::string()->max(20);        // at most 20 bytes
Expect::unicode()->min(1)->max(5); // 1..5 characters
```

--------------------------------

### Using Expect::anyOf with scalars, schemas, and firstIsDefault

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/AnyOf.md

Shows how to use Nette\Schema\Expect::anyOf() to accept multiple scalar values or schema variants. The first example validates a list of scalars, the second uses schemas as variants, and the third demonstrates firstIsDefault() with error handling that outputs a validation message.

```php
$processor = new Nette\Schema\Processor;

// scalars
$schema = Expect::listOf(Expect::anyOf('a', true, null));
$processor->process($schema, ['a', true, null]); // OK

// schemas as variants
$schema = Expect::anyOf(Expect::string(), true, null);
$processor->process($schema, 'foo');  // => 'foo'

// default from the first variant + error handling
$schema = Expect::anyOf('read', 'write')->firstIsDefault();
try {
	$processor->process($schema, 'delete');
} catch (Nette\Schema\ValidationException $e) {
	echo $e->getMessage(); // The item expects to be 'read'|'write', 'delete' given.
}
```

--------------------------------

### listOf() usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Creates a list schema where every element matches the given type. With wrap: true, a single non-array value is accepted and wrapped into a one-item list.

```php
$schema = Expect::listOf('string');
$schema = Expect::listOf('string', wrap: true);  // 'hello' -> ['hello']
```

--------------------------------

### EnumType usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/EnumType.md

Shows how to use Expect::enum() with a backed enum, processing values and handling validation errors.

```php
enum Suit: string
{
	case Hearts = 'hearts';
	case Spades = 'spades';
}

$processor = new Nette\Schema\Processor;

$schema = Expect::enum(Suit::class);
$processor->process($schema, 'hearts');     // => Suit::Hearts
$processor->process($schema, Suit::Spades); // => Suit::Spades

// error handling
try {
	$processor->process($schema, 'clubs');
} catch (Nette\Schema\ValidationException $e) {
	echo $e->getMessage(); // The item expects to be Suit, 'clubs' given.
}
```

--------------------------------

### Usage example of TypeExpression::parse() and format()

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/TypeExpression.md

Shows how to parse a type expression and format it back. The output is 'null|string' for the input 'null|string'.

```php
use Nette\Schema\TypeExpression;

$item = TypeExpression::parse('null|string'); // nullable string (Kind::String)
echo TypeExpression::format($item);
// null|string
```

--------------------------------

### Expect::type() usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Shows various type expressions passed to Expect::type(), including unions, null, email, pattern, and a class name. The last example uses instanceof for an enum class.

```php
$schema = Expect::type('int|string');
$schema = Expect::type('null|float');
$schema = Expect::type('email');
$schema = Expect::type('pattern:\d{9}');
$schema = Expect::type('AddressEntity'); // instanceof AddressEntity
```

--------------------------------

### addError() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Context.md

Example call to addError() with a message template, the Message::TypeMismatch error code, and an array of variables for placeholders. The method returns a Message object that can be used to push additional path segments.

```php
$context->addError(
	'The %label% %path% expects to be %expected%, %value% given.',
	Nette\Schema\Message::TypeMismatch,
	['value' => $value, 'expected' => 'int|string'],
);
```

--------------------------------

### Expect::from() usage example with Config class

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Defines a Config class with typed properties and then creates a schema from an instance, overriding the 'name' property with a pattern constraint. The result is a Structure that casts to Config::class.

```php
class Config
{
	public string $name;
	public string|null $password = null;
	public bool $admin = false;
}

$schema = Expect::from(new Config, [
	'name' => Expect::string()->pattern('\w:.*'),
]);
// $schema instanceof Structure, castTo Config::class
```

--------------------------------

### Chain multiple before() handlers

Source: https://github.com/nette/schema/blob/master/readme.md

Shows that before() can be called repeatedly (since version 2.0) and handlers are chained, each receiving the result of the previous one. The example converts a string to uppercase after exploding it.

```php
$schema = Expect::arrayOf('string')
	->before(fn($v) => explode(' ', $v))
	->before(fn($v) => array_map('strtoupper', $v));

$normalized = $processor->process($schema, 'a b c');
// OK and returns ['A', 'B', 'C']
```

--------------------------------

### before() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Base.md

Chains two before() callbacks to split a string and uppercase the parts. The first handler receives the raw input, the second receives the result of the first. For EnumType, the handler sees the raw input; backing-value mapping happens after.

```php
$schema = Expect::arrayOf('string')
	->before(fn($v) => explode(' ', $v))
	->before(fn($v) => array_map('strtoupper', $v));
```

--------------------------------

### Message usage example with toString()

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Message.md

Creates a Message instance with a template containing %label%, %path%, %expected%, and %value% placeholders, then calls toString() to render it. The output shows 'The item 'refundAmount' expects to be int, 'nope' given.'

```php
$m = new Message(
	'The %label% %path% expects to be %expected%, %value% given.',
	Message::TypeMismatch,
	['refundAmount'],
	['value' => 'nope', 'expected' => 'int'],
);
echo $m->toString();
// The item 'refundAmount' expects to be int, 'nope' given.
```

--------------------------------

### Expect::enum() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Accepts a case or its backing value and always returns the case. Backed-int enums behave identically.

```php
enum Suit: string
{
	case Hearts = 'hearts';
	case Spades = 'spades';
}

$schema = Expect::enum(Suit::class);
$processor->process($schema, 'hearts');     // => Suit::Hearts
$processor->process($schema, Suit::Spades); // => Suit::Spades
```

--------------------------------

### castTo() usage examples

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Base.md

Shows two ways to use castTo(): casting a string to a DateTime class and casting a structure to a custom class. The first casts a string to DateTime, the second casts a structure with boolean and integer fields to Info::class.

```php
$schema = Expect::string()->castTo(DateTime::class);
$schema = Expect::structure([
	'processRefund' => Expect::bool(),
	'refundAmount' => Expect::int(),
])->castTo(Info::class);
```

--------------------------------

### Expect::structure() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Creates a structure schema with two properties: processRefund as boolean and refundAmount as integer. Properties are optional by default with null default.

```php
$schema = Expect::structure([
	'processRefund' => Expect::bool(),
	'refundAmount' => Expect::int(),
]);
```

--------------------------------

### tuple() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Creates a fixed-size array schema with per-position schemas. Throws Nette\InvalidArgumentException if the shape is not an indexed array.

```php
$schema = Expect::tuple([
	Expect::int(),
	Expect::string(),
	Expect::bool(),
]);
```

--------------------------------

### pattern()

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/StringType.md

Sets a regex pattern the whole string must match. The pattern is anchored to start and end.

```APIDOC
## pattern()

### Description
Sets a regex pattern the whole string must match. The pattern is anchored to start and end.

### Signature
```php
public function pattern(?string $pattern): static
```

### Parameters
- `$pattern` (?string) - Required - PCRE pattern; matched as `^…$` (`\x01^(?:$pattern)$\x01Du`), `null` clears it

### Returns
- `static` - Returns the instance for chaining.

### Errors
- Violations produce `Message::PatternMismatch`.
- A pattern of a wrong kind throws `Nette\DeprecatedException`.
- An invalid pattern throws `Nette\InvalidStateException`.
```

--------------------------------

### Example: nullable string schema

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Type.md

Creates a schema that accepts 'abc' and null. Demonstrates the nullable() method on a string type.

```php
$schema = Expect::string()->nullable(); // accepts 'abc' and null
```

--------------------------------

### List of values with Expect::listOf

Source: https://github.com/nette/schema/blob/master/readme.md

Defines a list (indexed array) with string elements. The list must be indexed by sequential numeric keys starting from zero.

```php
$schema = Expect::listOf('string');

$processor->process($schema, ['a', 'b']); // OK
$processor->process($schema, ['a', 123]); // ERROR: 123 is not a string
$processor->process($schema, ['key' => 'a']); // ERROR: not a list
$processor->process($schema, [1 => 'a', 0 => 'b']); // ERROR: also not a list
```

--------------------------------

### Generate schema from class with Expect::from()

Source: https://github.com/nette/schema/blob/master/readme.md

Creates a structure schema from a class definition. The example defines a Config class and uses Expect::from(new Config) to generate a schema that validates and maps data to a Config instance.

```php
class Config
{
	public string $name;
	public string|null $password = null;
	public bool $admin = false;
}

$schema = Expect::from(new Config);

$data = [
	'name' => 'Frank',
];

$normalized = $processor->process($schema, $data);
// $normalized instanceof Config
// $normalized = {'name' => 'Frank', 'password' => null, 'admin' => false}
```

--------------------------------

### Supplement class schema with custom rules

Source: https://github.com/nette/schema/blob/master/readme.md

Uses the second parameter of Expect::from() to override or supplement the schema generated from a class. The example adds a pattern constraint to the 'name' property.

```php
$schema = Expect::from(new Config, [
	'name' => Expect::string()->pattern('\w:.*'),
]);
```

--------------------------------

### JSON Schema export example

Source: https://github.com/nette/schema/blob/master/readme.md

Shows the JSON Schema export format for a database configuration object. The export describes the shape of data (types, ranges, patterns, required items, enum values, and description texts) but omits default values, castTo(), and transform().

```json
{
	"type": "object",
	"properties": {
		"host": {"type": "string", "description": "Database server hostname"},
		"port": {"type": "integer", "minimum": 1, "maximum": 65535},
		"user": {"type": "string"}
	},
	"required": ["user"],
	"additionalProperties": false
}
```

--------------------------------

### Processor::skipDefaults method usage

Source: https://github.com/nette/schema/blob/master/_autodocs/configuration.md

Enable skipDefaults to prevent missing properties from being filled with their default values. The example shows that with skipDefaults enabled, processing a structure with a default value results in an empty stdClass.

```php
$processor = new Nette\Schema\Processor;
$processor->skipDefaults();
$processor->process(Expect::structure(['a' => Expect::int(1)]), []);
// => stdClass { } (the 'a' => 1 default is not filled)
```

--------------------------------

### Processor::onNewContext property usage

Source: https://github.com/nette/schema/blob/master/_autodocs/configuration.md

Attach a closure to the onNewContext property to observe or adjust the context at the start of every processing run. The closure receives the freshly created Context object.

```php
$processor = new Nette\Schema\Processor;
$processor->onNewContext[] = fn(Nette\Schema\Context $context) {
	// observe or adjust the context per run
};
```

--------------------------------

### Basic export example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/JsonSchema.md

Exports a structure schema with string, int, and required string fields to JSON Schema, then prints it as pretty JSON. The output shows the resulting JSON Schema object with properties, required, and additionalProperties.

```php
use Nette\Schema\JsonSchema;

$schema = Expect::structure([
	'host' => Expect::string('localhost')->description('Database server hostname'),
	'port' => Expect::int(3306)->min(1)->max(65535),
	'user' => Expect::string()->required(),
]);

echo json_encode(JsonSchema::export($schema), JSON_PRETTY_PRINT);
// {
//   "type": "object",
//   "properties": {
//     "host": {"type": "string", "description": "Database server hostname"},
//     "port": {"type": "integer", "minimum": 1, "maximum": 65535},
//     "user": {"type": "string"}
//   },
//   "required": ["user"],
//   "additionalProperties": false
// }
```

--------------------------------

### Normalize input with before() - explode string to array

Source: https://github.com/nette/schema/blob/master/readme.md

Uses the before() method to normalize data before validation. The example converts a space-separated string into an array of strings. The handler receives the raw input and returns the normalized value.

```php
$explode = fn($v) => explode(' ', $v);

$schema = Expect::arrayOf('string')
	->before($explode);

$normalized = $processor->process($schema, 'a b c');
// OK and returns ['a', 'b', 'c']
```

--------------------------------

### Define item and key schemas with items()

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/ArrayType.md

Example of using items() to set value type to string and key type to int. Without items(), colliding array pairs add a Message::CannotMerge error.

```php
$schema = Expect::array()->items('string', Expect::int());
```

--------------------------------

### Set merge strategy with mergeMode()

Source: https://github.com/nette/schema/blob/master/readme.md

Shows how to set the merge strategy for arrays and structures using mergeMode(). The example uses MergeMode::Replace to make the later array replace the earlier one.

```php
use Nette\Schema\MergeMode;

Expect::arrayOf('string')->mergeMode(MergeMode::Replace); // the later array replaces the earlier one
```

--------------------------------

### AnyOf::describe()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Returns a description of the AnyOf.

```APIDOC
## AnyOf::describe()

### Description
Returns a description of the AnyOf.

### Method
instance

### Endpoint
AnyOf::describe()

### Parameters
None

### Return Value
string - The description
```

--------------------------------

### deprecated() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Base.md

Example of using deprecated() on an integer field within a structure. Produces a warning on Context::$warnings but does not invalidate the data.

```php
$schema = Expect::structure([
	'old' => Expect::int()->deprecated('The item %path% is deprecated'),
]);
```

--------------------------------

### pattern() signature with docblock

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/StringType.md

Sets a regex pattern the whole string must match, anchored to start and end. Violations produce Message::PatternMismatch. A wrong kind throws Nette\DeprecatedException; an invalid pattern throws Nette\InvalidStateException.

```php
/**
 * Sets a regex pattern the whole string must match (anchored to start and end).
 */
public function pattern(?string $pattern): static
```

--------------------------------

### Custom ByteSizeSchema implementation

Source: https://github.com/nette/schema/blob/master/readme.md

Example of a reusable custom schema element for byte sizes in friendly notation like '512kB' or '2 MB'. It validates the input and returns the number of bytes. Errors are reported via $context->addError() and null is returned; the Processor collects all errors and throws them together.

```php
use Nette\Schema\Context;
use Nette\Schema\Schema;

class ByteSizeSchema implements Schema
{
	private const Units = ['b' => 1, 'kb' => 1024, 'mb' => 1024 ** 2, 'gb' => 1024 ** 3];

	public function normalize(mixed $value, Context $context): mixed
	{
		return is_int($value) ? "$value B" : $value; // unify both notations
	}

	public function merge(mixed $value, mixed $base, Context $context): mixed
	{
		return $value ?? $base; // the later value wins
	}

	public function complete(mixed $value, Context $context): mixed
	{
		if (!is_string($value) || !preg_match('~^(\d+)\s*([a-zA-Z]+)$~', $value, $m)) {
			$context->addError("The item %path% expects to be a size like '512kB'.", 'size.format');
			return null;
		}

		$unit = self::Units[strtolower($m[2])] ?? null;
		if ($unit === null) {
			$context->addError("The item %path% uses an unknown unit '$m[2]'.", 'size.unit');
			return null;
		}

		return (int) $m[1] * $unit;
	}

	public function completeDefault(Context $context): mixed
	{
		return null; // value used when the item is missing from the input
	}
}
```

--------------------------------

### Example: parse('int|string')

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/TypeExpression.md

Example call to TypeExpression::parse() with a union type expression. The returned array contains a Kind::Union with variants for int and string, plus nullable and dynamic flags set to false.

```php
$item = TypeExpression::parse('int|string');
// ['kind' => Kind::Union, 'variants' => [
//     ['kind' => Kind::Int, 'source' => 'int'],
//     ['kind' => Kind::String, 'source' => 'string'],
// ], 'nullable' => false, 'dynamic' => false]
```

--------------------------------

### onNewContext

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Processor.md

A public property that holds a list of closures invoked with the freshly created Context at the start of every processing run. This is the official integration hook for other packages to attach and inspect or modify the context before validation starts.

```APIDOC
## onNewContext

### Description
A public property that holds a list of closures invoked with the freshly created Context at the start of every processing run. This is the official integration hook for other packages to attach and inspect or modify the context before validation starts.

### Type
`array` of `Closure(Context): void`

### Usage
Assign closures to inspect or modify the context before validation starts.

### Example
```php
$processor = new Processor;
$processor->onNewContext[] = fn(Nette\Schema\Context $context) {
	// observe or modify the context for this run
};
```
```

--------------------------------

### describe()

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/StringType.md

Returns the base description plus `min`/`max` and `pattern`, threaded into every variant for a union of strings.

```APIDOC
## describe()

### Description
Returns the base description plus `min`/`max` and `pattern`, threaded into every variant for a union of strings.

### Signature
```php
public function describe(): array
```

### Returns
- `array` - The description array.
```

--------------------------------

### Using Expect::type() to create Type instances

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Type.md

Shows how to create Type instances via Expect::type() with various type expressions, including nullable types, and how to process values with the Processor, which returns the value or throws ValidationException on mismatch.

```php
$schema = Expect::type('int');          // new Type('int') via Expect::type
$schema = Expect::type('AddressEntity'); // instanceof check
$schema = Expect::type('bool')->nullable();

$processor = new Nette\Schema\Processor;
$processor->process(Expect::type('int'), 5);   // => 5
$processor->process(Expect::type('int'), 'x'); // throws ValidationException
```

--------------------------------

### Transform value with transform()

Source: https://github.com/nette/schema/blob/master/readme.md

Modifies successfully validated data using a custom function. The example converts a string to uppercase.

```php
// convert to uppercase:
Expect::string()->transform(fn(string $s) => strtoupper($s));
```

--------------------------------

### Add custom assertion with assert()

Source: https://github.com/nette/schema/blob/master/readme.md

Adds a custom constraint using a callable. The example checks that the count of an array is even.

```php
$countIsEven = fn($v) => count($v) % 2 === 0;

$schema = Expect::arrayOf('string')
	->assert($countIsEven); // the count must be even

$processor->process($schema, ['a', 'b']); // OK
$processor->process($schema, ['a', 'b', 'c']); // ERROR: 3 is not an even count
```

--------------------------------

### Context::createChecker()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Creates a checker for the context.

```APIDOC
## Context::createChecker()

### Description
Creates a checker for the context.

### Method
instance

### Endpoint
Context::createChecker()

### Parameters
None

### Return Value
callable - The checker function
```

--------------------------------

### Type::describe()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Returns a description of the type.

```APIDOC
## Type::describe()

### Description
Returns a description of the type.

### Method
instance

### Endpoint
Type::describe()

### Parameters
None

### Return Value
string - The description
```

--------------------------------

### Using dynamic() with Expect::string()

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Type.md

Example usage of the dynamic() method on a string type. The value can be a DynamicParameter, which is recorded for deferred validation.

```php
$schema = Expect::string()->dynamic();
```

--------------------------------

### StringType::describe()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Returns a description of the string type.

```APIDOC
## StringType::describe()

### Description
Returns a description of the string type.

### Method
instance

### Endpoint
StringType::describe()

### Parameters
None

### Return Value
string - The description
```

--------------------------------

### Attaching a closure to onNewContext

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Processor.md

Shows how to attach a closure to `$processor->onNewContext` to observe or modify the `Context` before validation starts. The closure receives a `Nette\Schema\Context` instance.

```php
$processor = new Processor;
$processor->onNewContext[] = fn(Nette\Schema\Context $context) {
	// observe or modify the context for this run
};
```

--------------------------------

### Structure::describe()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Returns a description of the structure.

```APIDOC
## Structure::describe()

### Description
Returns a description of the structure.

### Method
instance

### Endpoint
Structure::describe()

### Parameters
None

### Return Value
string - The description
```

--------------------------------

### Validate data that passes schema

Source: https://github.com/nette/schema/blob/master/readme.md

Sends data that passes validation, returning a stdClass object. To get an array, add ->castTo('array') to the schema.

```php
$data = [
	'processRefund' => true,
	'refundAmount' => 17,
];

$normalized = $processor->process($schema, $data); // OK, passes validation
```

--------------------------------

### TupleType::describe()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Returns a description of the tuple type.

```APIDOC
## TupleType::describe()

### Description
Returns a description of the tuple type.

### Method
instance

### Endpoint
TupleType::describe()

### Parameters
None

### Return Value
string - The description
```

--------------------------------

### required() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Base.md

Shows marking a string as required and an optional nested structure. A missing required item produces Message::MissingItem unless in partial/probe mode.

```php
$schema = Expect::structure([
	'name' => Expect::string()->required(),
	'db'   => Expect::structure([...])->required(false), // optional nested structure
]);
```

--------------------------------

### Chain castTo(), assert(), and transform()

Source: https://github.com/nette/schema/blob/master/readme.md

Shows the order of operations when chaining castTo(), assert(), and transform(). Operations are performed in the order declared.

```php
Expect::type('string|int')
	->castTo('string')
	->assert('ctype_lower', 'All characters must be lowercased')
	->transform(fn(string $s) => strtoupper($s)); // convert to uppercase
```

--------------------------------

### AnyOf::firstIsDefault()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Sets the first schema as the default.

```APIDOC
## AnyOf::firstIsDefault()

### Description
Sets the first schema as the default.

### Method
instance

### Endpoint
AnyOf::firstIsDefault()

### Parameters
None

### Return Value
static - The AnyOf instance
```

--------------------------------

### Custom merge logic with mergeWith()

Source: https://github.com/nette/schema/blob/master/readme.md

Uses mergeWith() to provide a custom function for merging values. The example combines boolean values with a logical OR, so once enabled, it stays enabled.

```php
Expect::bool()->mergeWith(fn($value, $base) => $value || $base); // once enabled, stays enabled
```

--------------------------------

### Deprecated option methods (throw)

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/AnyOf.md

Mirror methods that always throw Nette\DeprecatedException, telling you to give the option to the variants. These methods are deprecated and should not be used.

```APIDOC
## Deprecated option methods (throw)

### Description
`min()`, `max()`, `pattern()`, `items()`, `mergeDefaults()` are mirror methods that always throw `Nette\DeprecatedException` telling you to give the option to the variants. Each is marked with `#[
Deprecated]`.

### Methods
```php
public function min(int|float|null $min): self
public function max(int|float|null $max): self
public function pattern(?string $pattern): self
public function items(string|Schema $valueType = 'mixed', string|Schema|null $keyType = null): self
public function mergeDefaults(bool $state = true): self
```

### Source
`src/Schema/Elements/AnyOf.php:81`–`111`

### Example
```php
Expect::anyOf(1, 2)->min(1); // throws Nette\DeprecatedException: min() is not available on anyOf()
```
```

--------------------------------

### StringType::min()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Sets the minimum length for the string.

```APIDOC
## StringType::min()

### Description
Sets the minimum length for the string.

### Method
instance

### Endpoint
StringType::min()

### Parameters
- **length** (int) - Required - The minimum length

### Return Value
static - The type instance
```

--------------------------------

### transform() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Base.md

Shows a transform() callback that validates the string is lowercase and returns it uppercased, or reports an error via Context. The handler stops remaining transforms if it reports an error.

```php
$schema = Expect::string()
	->transform(function (string $s, Nette\Schema\Context $context) {
		if (!ctype_lower($s)) {
			$context->addError('All characters must be lowercased', 'my.case.error');
			return null;
		}
		return strtoupper($s);
	});
```

--------------------------------

### Expect::list()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Static factory method to create a list type expectation. Returns an ArrayType object for validation.

```APIDOC
## Expect::list()

### Description
Static factory method to create a list type expectation. Returns an ArrayType object for validation.

### Method
static

### Endpoint
Expect::list()

### Parameters
None

### Return Value
ArrayType object
```

--------------------------------

### Assert file existence with assert()

Source: https://github.com/nette/schema/blob/master/readme.md

Uses a built-in function as an assertion to require that the value is an existing file.

```php
Expect::string()->assert('is_file'); // file must exist
```

--------------------------------

### Expect::unicode()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Static factory method to create a unicode type expectation. Returns a StringType object for validation.

```APIDOC
## Expect::unicode()

### Description
Static factory method to create a unicode type expectation. Returns a StringType object for validation.

### Method
static

### Endpoint
Expect::unicode()

### Parameters
None

### Return Value
StringType object
```

--------------------------------

### ArrayType::describe()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Returns a description of the array type.

```APIDOC
## ArrayType::describe()

### Description
Returns a description of the array type.

### Method
instance

### Endpoint
ArrayType::describe()

### Parameters
None

### Return Value
string - The description
```

--------------------------------

### mergeWith() usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Base.md

Uses mergeWith() to implement a boolean OR combiner so that once a value is enabled, it stays enabled. The combiner runs only between layers (n−1 times), never on a single layer, and receives already-normalized data.

```php
$schema = Expect::bool()->mergeWith(fn($value, $base) => $value || $base); // once enabled, stays enabled
```

--------------------------------

### Merging multiple configuration layers with processMultiple()

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Processor.md

Shows how later layers override earlier ones. The result is a stdClass with merged values: host from defaults, port and logging from userConfig.

```php
$defaults   = ['host' => 'localhost', 'port' => 3306, 'logging' => false];
$userConfig = ['port' => 5432, 'logging' => true];

$config = $processor->processMultiple(
	Expect::structure([
		'host' => Expect::string(),
		'port' => Expect::int(),
		'logging' => Expect::bool(),
	]),
	[$defaults, $userConfig],
);
// => stdClass { host: 'localhost', port: 5432, logging: true }
```

--------------------------------

### Expect::string()->min() / max()

Source: https://github.com/nette/schema/blob/master/readme.md

Limits the length of a string in bytes to a minimum and/or maximum. Use Expect::unicode() for character count.

```APIDOC
## Expect::string()->min() / max()

### Description
Limits the length of a string in bytes to a minimum and/or maximum. Use Expect::unicode() for character count.

### Method
Expect::string()->min() / max()

### Parameters
- **min** (int) - Optional - Minimum length in bytes.
- **max** (int) - Optional - Maximum length in bytes.

### Request Example
```php
// string, at least 10 bytes long, maximum 20 bytes
Expect::string()->min(10)->max(20);
```

### Response
Returns a schema object with the specified constraints.
```

--------------------------------

### Export schema to JSON Schema with JsonSchema::export()

Source: https://github.com/nette/schema/blob/master/readme.md

Converts a Nette Schema to a JSON Schema document using JsonSchema::export(). The example defines a structure schema and outputs the JSON Schema as pretty-printed JSON.

```php
use Nette\Schema\JsonSchema;

$schema = Expect::structure([
	'host' => Expect::string('localhost')->description('Database server hostname'),
	'port' => Expect::int(3306)->min(1)->max(65535),
	'user' => Expect::string()->required(),
]);

echo json_encode(JsonSchema::export($schema), JSON_PRETTY_PRINT);
```

--------------------------------

### AnyOf::dynamic()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Marks the AnyOf as dynamic.

```APIDOC
## AnyOf::dynamic()

### Description
Marks the AnyOf as dynamic.

### Method
instance

### Endpoint
AnyOf::dynamic()

### Parameters
None

### Return Value
static - The AnyOf instance
```

--------------------------------

### Deprecated min() method throws exception

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Type.md

Calling min() on a plain Type throws Nette\DeprecatedException advising that min() is only available on number, string, or array types. This example shows the exception message for a bool type.

```php
Expect::bool()->min(2);
// throws Nette\DeprecatedException: min() is not available on 'bool', ...
```

--------------------------------

### Expect::string()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Static factory method to create a string type expectation. Returns a StringType object for validation.

```APIDOC
## Expect::string()

### Description
Static factory method to create a string type expectation. Returns a StringType object for validation.

### Method
static

### Endpoint
Expect::string()

### Parameters
None

### Return Value
StringType object
```

--------------------------------

### Expect magic methods signature (docblock)

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Expect.md

Lists the magic static methods available on Expect via __callStatic(). Each method returns a schema element and accepts an optional default value.

```php
/**
 * @method static AnyOf scalar($default = null)
 * @method static StringType string($default = null)
 * @method static NumberType int($default = null)
 * @method static NumberType float($default = null)
 * @method static Type bool($default = null)
 * @method static Type null()
 * @method static ArrayType list($default = [])
 * @method static Type mixed($default = null)
 * @method static StringType email($default = null)
 * @method static StringType unicode($default = null)
 */
```

--------------------------------

### NumberType usage example

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/NumberType.md

Shows basic usage with min/max, float vs int distinction, and error handling. Out-of-range values throw ValidationException with a message like 'The item expects to be in range 10..100, 5 given.'

```php
$processor = new Nette\Schema\Processor;

// basic
$schema = Expect::int()->min(10)->max(100);
$processor->process($schema, 50);  // => 50
$processor->process($schema, 5);   // throws: The item expects to be in range 10..100, 5 given.

// float vs int distinction comes from the type expression
$processor->process(Expect::type('float'), 1.5); // => 1.5
$processor->process(Expect::type('float'), 1);   // throws: expects to be float
$processor->process(Expect::type('number'), 1);  // => 1 (int|float union)

// error handling
try {
	$processor->process(Expect::int()->min(1), 0);
} catch (Nette\Schema\ValidationException $e) {
	echo $e->getMessage(); // The item expects to be in range 1.., 0 given.
}
```

--------------------------------

### describe() signature

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/ArrayType.md

Returns an array describing the element, adding items, keys, and wrap when items exist.

```php
public function describe(): array
```

--------------------------------

### onNewContext property declaration

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Processor.md

Declares the public array property `onNewContext` that holds closures invoked with a fresh `Context` at the start of each processing run. Used as an integration hook for packages like `nette/di` to inspect or modify the context before validation.

```php
/** @var list<\Closure(Context): void> */
public array $onNewContext = [];
```

--------------------------------

### Using getWarnings() with deprecated()

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/Processor.md

Processes a schema with a deprecated item and retrieves the collected warning messages. The warning message uses the %path% placeholder, which is replaced with the item's path. The process call succeeds (OK) and getWarnings() returns the rendered warning.

```php
$processor = new Processor;
$schema = Expect::structure([
	'old' => Expect::int()->deprecated('The item %path% is deprecated'),
]);

$processor->process($schema, ['old' => 1]); // OK
$processor->getWarnings(); // ["The item 'old' is deprecated"]

```

--------------------------------

### firstIsDefault() signature

Source: https://github.com/nette/schema/blob/master/_autodocs/api-reference/AnyOf.md

Signature for the firstIsDefault() method. Sets the first variant as the default value instead of null.

```php
public function firstIsDefault(): self
```

--------------------------------

### Tuple with tuple()

Source: https://github.com/nette/schema/blob/master/readme.md

Defines a fixed-size array where each position has its own schema. Processing a matching list succeeds.

```php
$schema = Expect::tuple([
	Expect::int(),
	Expect::string(),
	Expect::bool(),
]);

$processor->process($schema, [1, 'hello', true]); // OK
```

--------------------------------

### Structure::min()

Source: https://github.com/nette/schema/blob/master/_autodocs/README.md

Sets the minimum number of properties for the structure.

```APIDOC
## Structure::min()

### Description
Sets the minimum number of properties for the structure.

### Method
instance

### Endpoint
Structure::min()

### Parameters
- **count** (int) - Required - The minimum number of properties

### Return Value
static - The structure instance
```
Tokens:
Raw