php-dextrin

Registry
in package

FinalYes

Extension point for both `struct` and `custom-tag` decoding/encoding.

No entry for a given name -> decode falls back to an opaque DXNStruct/DXNCustomTag -- never a hard failure, since neither type requires a registration to be representable at all.

Struct entries only ever come from a compiled .dxns schema (Compiler) plus an optional materializer layered on top -- there is no putStruct that hand-writes a struct's shape directly, because struct is schema-dependent by design: the schema supplies field names/order/types, a materializer only decides what nicer decoded shape to produce from an already-schema-validated field map.

Immutable-by-convention: every put* method returns a new Registry, never mutates $this -- threaded explicitly through decode/encode/Schema::compile, never a global or a class with hidden state.

Deliberate omission vs. the Elixir and JS ports: no trusted/putTrusted. Both mirror it purely to gate whether keyword decodes as an interned atom/Symbol.for (trusted) or a plain wrapper (untrusted) -- this port's keyword always decodes as DXNKeyword regardless, since PHP has no atom table or global symbol registry whose exhaustion untrusted input could threaten in the first place (see DXNKeyword's own doc).

Table of Contents

Properties

$materializers  : array<string, callable(string, int, array<int|string, mixed>): mixed>
$resolver  : Warning: Array to string conversion in /opt/phpdoc/src/phpDocumentor/Transformer/Writer/Twig/LinkRenderer/CallableAdapter.php on line 87 callable(string): Array|null
$strict  : bool
Whether this registry decodes strictly ({@see putStrict()}).
$structModules  : array<string, class-string>
$structs  : array<string|int, mixed>
$tagEncoders  : array<class-string, array{0: string, 1: callable}>
$tags  : array<string, callable(mixed): mixed>
$typeAliases  : array<string, TypeExpr>

Methods

addStructSchema()  : self
Loads `$compiled` as a new version of the schema `$name`. A version that is already loaded is refused as `schema/duplicate-version` (DXNS.md §8): two documents both claiming to be `User` v3 is a mistake, not an update.
asWritten()  : DXNStruct
`$struct` as it is written here: carrying the latest loaded version of its schema (DXNS.md §8), whatever version it says itself. A struct whose name has no schema keeps its own version, or none.
fetchMaterializer()  : callable(string, int, array<int|string, mixed>): mixed|null
fetchSchemaNameForModule()  : string|null
The reverse of {@see self::fetchStructModule()}: given an application value's own class, finds the schema name it was registered under (if any) -- what lets automatic encode-time validation recognize a plain PHP class instance as "this is a Foo" without being told so explicitly.
fetchStructModule()  : class-string|null
fetchStructSchema()  : FetchedSchema|null
Looks up a compiled schema by struct name: the latest version, or with `$version` exactly that one. A name not loaded at all consults the lazy resolver (if any), which loads every version it finds. Whether schemas are all compiled up front or resolved on demand (a resolver reading a file, calling a schema service, ...) is entirely the caller's choice -- this is what makes both paths look identical to everything else. **A named version never falls back to another**: a struct is only ever read with the schema it was written against.
fetchTag()  : callable(mixed): mixed|null
fetchTagEncoder()  : array{0: string, 1: callable}|null
fetchTypeAlias()  : TypeExpr|null
isStrict()  : bool
putResolver()  : self
A lazy source of schemas, asked on a miss for a name: every version it finds -- one compiled schema or a list of them, all loaded -- or null. It throws a {@see \JOetjen\Dextrin\Schema\SchemaCompileError} when the schemas it found cannot be used: two files with one version, a file that is not the version its name says, .
putStrict()  : self
Marks this registry as decoding *strictly*: a schema-backed struct that carries a field its schema does not declare is refused (`schema/undeclared-field`, DXNS.md §7) instead of keeping it as an extra field. A config loader decodes strictly; a message consumer does not. {@see \JOetjen\Dextrin\Dextrin::decode()} and `decodeBinary()` take it as `strict: true`.
putStructMaterializer()  : self
The schema's materializer (DXNS.md §8): called for every decoded struct of `$name`, whatever the version, with the schema's name, the version the fields were read with and the fields keyed by name; it answers the application's latest-version value, which is checked against the latest schema, or throws.
putStructModule()  : self
Declares which PHP class a schema's data is expected to be -- used only for `{form: 'reference', name}` checks during encode-time validation. Decode-time reference checks don't need this: they carry an internal provenance marker regardless of materializer shape ({@see \JOetjen\Dextrin\Schema\Validated}).
putStructSchema()  : self
`$compiled` as version `$compiled->version` of the schema `$name`, whether or not that version was loaded already -- the unchecked setter a resolver's answer goes through. Loading a document's schemas goes through {@see addStructSchema()}, a hot swap through {@see replaceStructSchema()}.
putTag()  : self
putTagEncoder()  : self
The reverse of {@see self::putTag()}: registers how to turn an application value (keyed by its class) back into `@name value` on encode -- decode-side dispatch happens by wire tag name, encode needs to dispatch by PHP class instead, so the two directions need separate tables.
putTypeAlias()  : self
replaceStructSchema()  : self
Replaces version `$compiled->version` of the schema `$name` -- the hot swap of a running system. **Replace only replaces**: a version that is not loaded is refused as `schema/not-loaded`, so a typo in a hot swap never quietly adds a version instead.
structSchemas()  : array<string|int, mixed>
Every loaded struct schema, by name and version -- what the version discipline check ({@see \JOetjen\Dextrin\Schema\Compat}) compares.
typeAliases()  : array<string, TypeExpr>
clone()  : self
isLoaded()  : bool
resolve()  : FetchedSchema|null
What the resolver answers for `$name`, every version of it loaded -- so an older struct reaches the materializer (DXNS.md §6, §4.8) -- and the latest answered. A resolver's refusal is thrown on.

Properties

$materializers

private array<string, callable(string, int, array<int|string, mixed>): mixed> $materializers = []

struct name -> materializer.

$resolver

private Warning: Array to string conversion in /opt/phpdoc/src/phpDocumentor/Transformer/Writer/Twig/LinkRenderer/CallableAdapter.php on line 87 callable(string): Array|null $resolver = null

$strict

Whether this registry decodes strictly ({@see putStrict()}).

private bool $strict = false

$structModules

private array<string, class-string> $structModules = []

struct name -> PHP class.

$structs

private array<string|int, mixed> $structs = []

$tagEncoders

private array<class-string, array{0: string, 1: callable}> $tagEncoders = []

class -> [tag name, encoder].

$tags

private array<string, callable(mixed): mixed> $tags = []

tag name -> decoder.

$typeAliases

private array<string, TypeExpr> $typeAliases = []

named type -> compiled type expression.

Methods

addStructSchema()

Loads `$compiled` as a new version of the schema `$name`. A version that is already loaded is refused as `schema/duplicate-version` (DXNS.md §8): two documents both claiming to be `User` v3 is a mistake, not an update.

public addStructSchema(string $name, Compiled $compiled) : self
Parameters
$name : string
$compiled : Compiled
Tags
throws
DXNError
Return values
self

asWritten()

`$struct` as it is written here: carrying the latest loaded version of its schema (DXNS.md §8), whatever version it says itself. A struct whose name has no schema keeps its own version, or none.

public asWritten(DXNStruct $struct) : DXNStruct

Every writer goes through this -- text, the formatter and binary -- so encoding never writes a version other than the latest, and never writes one no schema stands behind.

Parameters
$struct : DXNStruct
Return values
DXNStruct

fetchMaterializer()

public fetchMaterializer(string $name) : callable(string, int, array<int|string, mixed>): mixed|null
Parameters
$name : string
Return values
callable(string, int, array<int|string, mixed>): mixed|null

fetchSchemaNameForModule()

The reverse of {@see self::fetchStructModule()}: given an application value's own class, finds the schema name it was registered under (if any) -- what lets automatic encode-time validation recognize a plain PHP class instance as "this is a Foo" without being told so explicitly.

public fetchSchemaNameForModule(class-string $class) : string|null
Parameters
$class : class-string
Return values
string|null

fetchStructModule()

public fetchStructModule(string $name) : class-string|null
Parameters
$name : string
Return values
class-string|null

fetchStructSchema()

Looks up a compiled schema by struct name: the latest version, or with `$version` exactly that one. A name not loaded at all consults the lazy resolver (if any), which loads every version it finds. Whether schemas are all compiled up front or resolved on demand (a resolver reading a file, calling a schema service, ...) is entirely the caller's choice -- this is what makes both paths look identical to everything else. **A named version never falls back to another**: a struct is only ever read with the schema it was written against.

public fetchStructSchema(string $name[, int|null $version = null ]) : FetchedSchema|null
Parameters
$name : string
$version : int|null = null
Return values
FetchedSchema|null

fetchTag()

public fetchTag(string $name) : callable(mixed): mixed|null
Parameters
$name : string
Return values
callable(mixed): mixed|null

fetchTagEncoder()

public fetchTagEncoder(class-string $class) : array{0: string, 1: callable}|null
Parameters
$class : class-string
Return values
array{0: string, 1: callable}|null

fetchTypeAlias()

public fetchTypeAlias(string $name) : TypeExpr|null
Parameters
$name : string
Return values
TypeExpr|null

isStrict()

public isStrict() : bool
Return values
bool

putResolver()

A lazy source of schemas, asked on a miss for a name: every version it finds -- one compiled schema or a list of them, all loaded -- or null. It throws a {@see \JOetjen\Dextrin\Schema\SchemaCompileError} when the schemas it found cannot be used: two files with one version, a file that is not the version its name says, .

public putResolver( Warning: Array to string conversion in /opt/phpdoc/src/phpDocumentor/Transformer/Writer/Twig/LinkRenderer/CallableAdapter.php on line 87 callable(string): Array $resolver) : self

..

Parameters
$resolver : Warning: Array to string conversion in /opt/phpdoc/src/phpDocumentor/Transformer/Writer/Twig/LinkRenderer/CallableAdapter.php on line 87 callable(string): Array
Return values
self

putStrict()

Marks this registry as decoding *strictly*: a schema-backed struct that carries a field its schema does not declare is refused (`schema/undeclared-field`, DXNS.md §7) instead of keeping it as an extra field. A config loader decodes strictly; a message consumer does not. {@see \JOetjen\Dextrin\Dextrin::decode()} and `decodeBinary()` take it as `strict: true`.

public putStrict(bool $strict) : self
Parameters
$strict : bool
Return values
self

putStructMaterializer()

The schema's materializer (DXNS.md §8): called for every decoded struct of `$name`, whatever the version, with the schema's name, the version the fields were read with and the fields keyed by name; it answers the application's latest-version value, which is checked against the latest schema, or throws.

public putStructMaterializer(string $name, callable(string, int, array<int|string, mixed>): mixed $materializer) : self
Parameters
$name : string
$materializer : callable(string, int, array<int|string, mixed>): mixed
Return values
self

putStructModule()

Declares which PHP class a schema's data is expected to be -- used only for `{form: 'reference', name}` checks during encode-time validation. Decode-time reference checks don't need this: they carry an internal provenance marker regardless of materializer shape ({@see \JOetjen\Dextrin\Schema\Validated}).

public putStructModule(string $name, class-string $class) : self
Parameters
$name : string
$class : class-string
Return values
self

putStructSchema()

`$compiled` as version `$compiled->version` of the schema `$name`, whether or not that version was loaded already -- the unchecked setter a resolver's answer goes through. Loading a document's schemas goes through {@see addStructSchema()}, a hot swap through {@see replaceStructSchema()}.

public putStructSchema(string $name, Compiled $compiled) : self
Parameters
$name : string
$compiled : Compiled
Return values
self

putTag()

public putTag(string $name, callable(mixed): mixed $decoder) : self
Parameters
$name : string
$decoder : callable(mixed): mixed
Return values
self

putTagEncoder()

The reverse of {@see self::putTag()}: registers how to turn an application value (keyed by its class) back into `@name value` on encode -- decode-side dispatch happens by wire tag name, encode needs to dispatch by PHP class instead, so the two directions need separate tables.

public putTagEncoder(class-string $class, string $name, callable(object): mixed $encoder) : self
Parameters
$class : class-string
$name : string
$encoder : callable(object): mixed
Return values
self

putTypeAlias()

public putTypeAlias(string $name, TypeExpr $typeExpr) : self
Parameters
$name : string
$typeExpr : TypeExpr
Return values
self

replaceStructSchema()

Replaces version `$compiled->version` of the schema `$name` -- the hot swap of a running system. **Replace only replaces**: a version that is not loaded is refused as `schema/not-loaded`, so a typo in a hot swap never quietly adds a version instead.

public replaceStructSchema(string $name, Compiled $compiled) : self
Parameters
$name : string
$compiled : Compiled
Tags
throws
DXNError
Return values
self

structSchemas()

Every loaded struct schema, by name and version -- what the version discipline check ({@see \JOetjen\Dextrin\Schema\Compat}) compares.

public structSchemas() : array<string|int, mixed>
Return values
array<string|int, mixed>

clone()

private clone() : self
Return values
self

isLoaded()

private isLoaded(string $name, int $version) : bool
Parameters
$name : string
$version : int
Return values
bool

resolve()

What the resolver answers for `$name`, every version of it loaded -- so an older struct reaches the materializer (DXNS.md §6, §4.8) -- and the latest answered. A resolver's refusal is thrown on.

private resolve(string $name) : FetchedSchema|null
Parameters
$name : string
Return values
FetchedSchema|null
On this page

Search results