php-dextrin

Schema
in package

FinalYes

Public entry point for `.dxns` schema compilation and validation.

  • self::compile() -- the one-time walk from a decoded .dxns document to a populated Registry.
    • self::validate() -- checks an already-decoded value against a named schema (decode-side, but not decode itself -- see its own doc).
    • self::validateEncode()/self::validateEncodeTree() -- the encode-side mirror, one named schema vs. an automatic whole-tree walk. Unlike the Elixir original, both may transform the value they check (see Validator's own doc on schema-driven coercion).
    • self::annotations() -- what a {:doc} around a schema or named type says about it (DXNS.md §1b).

Enforcement during actual decoding is fail-fast and automatic: every registered struct name is checked unconditionally as part of Dextrin::decode()/Dextrin::decodeBinary(). The methods here are for the cases that aren't "check while decoding" (see self::validate()'s own doc).

Table of Contents

Methods

annotations()  : array<string, mixed>|null
What the `{:doc ... %{...}}` around the schema or named type `$name` says about it (DXNS.md §1b): its annotations by name, `[]` when it has none, `null` when `$registry` knows no such name. A schema answers for its latest version. An enum's `values` are a map, as a decode builds one, from each value to its own annotations by name.
check()  : true
Whether `$value` -- data a program already holds -- matches the definition `$name` in `$registry`: a struct schema, a `%shape` or a named type (design/shapes-and-case.md). Only a check: `$value` is never changed. Returns `true`, or throws the error saying why.
compat()  : array{problems: list>, upgrades: list>}
The version discipline check ({@see Compat}, DXNS.md §8): `$old`'s schemas against `$new`'s, as the problems -- a version whose content changed without a new version, a version that went down -- and what the latest versions' materializers have to upgrade.
compile()  : Registry
Compiles a decoded `.dxns` document into `$baseRegistry` -- a struct schema for each `%schema(N){}` entry, and a reusable named type for every other entry. `$names`, when given, maps each entry's key to the full name a tree gives it (DXNS.md §6) -- how {@see Schema\Tree} compiles a file -- a bare symbol naming a sibling resolving to it.
compileAll()  : Registry
Compiles several decoded `.dxns` documents into one registry, in order, over `$baseRegistry` (a new one by default) -- each seeing the schemas and named types of those before it, as {@see compile()} called on each in turn. The first that does not compile throws, naming which it was (`schema/compile`). As the reference's `Dextrin.Schema.compile_all/2`.
conform()  : mixed
`$value` checked as {@see self::check()} checks it, returned with every shape's missing defaults filled in, as a decode fills them; throws the error saying why it does not match.
registerProvider()  : Registry
Compiles and registers one schema provider ({@see \JOetjen\Dextrin\Schema\Provider}) into `$registry` -- lets a class's own library ship its DXN schema without that library depending on this one.
validate()  : true
Validates an already-decoded value against a named, compiled schema -- for the cases that aren't "check while decoding": a value built directly in PHP before encoding, an opaque `DXNStruct` decoded before a schema became available, or checking against a different schema than the one originally used. Returns `true` on success, throws {@see SchemaValidationError} on failure.
validateEncode()  : mixed
Encode-time schema validation: checks `$value` -- ordinary PHP data you're about to encode -- against a named, compiled schema *before* encoding produces any output. The mirror image of {@see self::validate()}, for data on its way out rather than in.
validateEncodeTree()  : mixed
Automatic, name-driven encode-time validation: walks `$value` and checks *every* `DXNStruct` or registered application class instance anywhere in it against its own schema, wherever it turns out to be. Symmetric to how decode checks every named struct unconditionally. `Dextrin::encode()`/`encodeBinary()` call this automatically by default. Returns the checked tree.
__construct()  : mixed

Methods

annotations()

What the `{:doc ... %{...}}` around the schema or named type `$name` says about it (DXNS.md §1b): its annotations by name, `[]` when it has none, `null` when `$registry` knows no such name. A schema answers for its latest version. An enum's `values` are a map, as a decode builds one, from each value to its own annotations by name.

public static annotations(Registry $registry, string $name) : array<string, mixed>|null 
$registry = Schema::compile(Dextrin::decode('%{Port: {:doc :integer %{description: "A TCP port"}}}'), new Registry());
Schema::annotations($registry, 'Port'); // ['description' => 'A TCP port']
Parameters
$registry : Registry

the compiled schemas and named types

$name : string

the schema's or named type's name

Return values
array<string, mixed>|null

check()

Whether `$value` -- data a program already holds -- matches the definition `$name` in `$registry`: a struct schema, a `%shape` or a named type (design/shapes-and-case.md). Only a check: `$value` is never changed. Returns `true`, or throws the error saying why.

public static check(mixed $value, Registry $registry, string $name) : true
Parameters
$value : mixed
$registry : Registry
$name : string
Return values
true

compat()

The version discipline check ({@see Compat}, DXNS.md §8): `$old`'s schemas against `$new`'s, as the problems -- a version whose content changed without a new version, a version that went down -- and what the latest versions' materializers have to upgrade.

public static compat(Registry $old, Registry $new) : array{problems: list>, upgrades: list>}
Parameters
$old : Registry
$new : Registry
Return values
array{problems: list>, upgrades: list>}

compile()

Compiles a decoded `.dxns` document into `$baseRegistry` -- a struct schema for each `%schema(N){}` entry, and a reusable named type for every other entry. `$names`, when given, maps each entry's key to the full name a tree gives it (DXNS.md §6) -- how {@see Schema\Tree} compiles a file -- a bare symbol naming a sibling resolving to it.

public static compile(mixed $schemaDoc, Registry $baseRegistry[, array<string, string> $names = [] ]) : Registry
Parameters
$schemaDoc : mixed
$baseRegistry : Registry
$names : array<string, string> = []
Return values
Registry

compileAll()

Compiles several decoded `.dxns` documents into one registry, in order, over `$baseRegistry` (a new one by default) -- each seeing the schemas and named types of those before it, as {@see compile()} called on each in turn. The first that does not compile throws, naming which it was (`schema/compile`). As the reference's `Dextrin.Schema.compile_all/2`.

public static compileAll(array<int, mixed> $schemaDocs[, Registry|null $baseRegistry = null ]) : Registry
Parameters
$schemaDocs : array<int, mixed>
$baseRegistry : Registry|null = null
Return values
Registry

conform()

`$value` checked as {@see self::check()} checks it, returned with every shape's missing defaults filled in, as a decode fills them; throws the error saying why it does not match.

public static conform(mixed $value, Registry $registry, string $name) : mixed
Parameters
$value : mixed
$registry : Registry
$name : string

registerProvider()

Compiles and registers one schema provider ({@see \JOetjen\Dextrin\Schema\Provider}) into `$registry` -- lets a class's own library ship its DXN schema without that library depending on this one.

public static registerProvider(Registry $registry, DXNSchemaProvider $provider) : Registry
Parameters
$registry : Registry
$provider : DXNSchemaProvider
Return values
Registry

validate()

Validates an already-decoded value against a named, compiled schema -- for the cases that aren't "check while decoding": a value built directly in PHP before encoding, an opaque `DXNStruct` decoded before a schema became available, or checking against a different schema than the one originally used. Returns `true` on success, throws {@see SchemaValidationError} on failure.

public static validate(mixed $value, Registry $registry, string $schemaName) : true
Parameters
$value : mixed
$registry : Registry
$schemaName : string
Return values
true

validateEncode()

Encode-time schema validation: checks `$value` -- ordinary PHP data you're about to encode -- against a named, compiled schema *before* encoding produces any output. The mirror image of {@see self::validate()}, for data on its way out rather than in.

public static validateEncode(mixed $value, Registry $registry, string $schemaName) : mixed

Returns the checked value, stripped of internal bookkeeping; nothing is converted (DXNS.md §7).

Parameters
$value : mixed
$registry : Registry
$schemaName : string

validateEncodeTree()

Automatic, name-driven encode-time validation: walks `$value` and checks *every* `DXNStruct` or registered application class instance anywhere in it against its own schema, wherever it turns out to be. Symmetric to how decode checks every named struct unconditionally. `Dextrin::encode()`/`encodeBinary()` call this automatically by default. Returns the checked tree.

public static validateEncodeTree(mixed $value, Registry $registry) : mixed
Parameters
$value : mixed
$registry : Registry

__construct()

private __construct() : mixed
On this page

Search results