Dextrin
in package
Public API entry point: `.dxn` text and `.dxnb` binary decode/ encode, plus `.dxns` schema-backed struct decoding and encode-time validation via an optional {@see Registry}.
This is a port of dextrin (Elixir, on Hex.pm), the reference
implementation. A sibling of node-dextrin (Node.js, on npm) reads
and writes the exact same .dxn/.dxnb/.dxns documents -- see
the README's own "Other language implementations" section.
Table of Contents
Methods
- decode() : mixed
- Decodes `.dxn` text into a value -- every DXN type maps to a native PHP value or a `DXN*` wrapper class, see the project's value-model mapping (`README.md`) for the full picture. Throws {@see DXNError} on malformed input, including a schema violation for any registered `struct` name the text uses.
- decodeBinary() : mixed
- Decodes a `.dxnb` binary string into a value -- the same value shapes as {@see self::decode()}. Same `$registry` effect. Throws {@see DXNError} on malformed input, including a missing/invalid envelope (`DX` + version byte) or a schema violation.
- encode() : string
- Encodes a value back to `.dxn` text. Single-line, minimal-whitespace by default; pass `pretty: true` for multi-line, indented output instead (`indent` then sets spaces per nesting level, default 2). Both produce the exact same value on the way back through `decode()` -- `pretty`/`indent` are a rendering choice, never a semantic one. Throws {@see DXNError} for a value with no DXN representation, or that fails schema validation.
- encodeBinary() : string
- Encodes a value to `.dxnb` binary, returning a raw binary string. Same `$registry`/`$validate`/`$coerce`/`$schema` parameters as {@see self::encode()}. Throws {@see DXNError} for a value with no DXN representation, or that fails schema validation.
- __construct() : mixed
- maybeValidateEncode() : mixed
- Two independent checks, both applied when requested: the automatic whole-tree walk (every named struct anywhere in `$value`, driven by whether a schema is registered for its name) and, only if `$schema` was given, a check of the (possibly already-coerced) result against that one named schema. Both may return a *transformed* value when `$coerce` (default `true`) lets a mismatched field be coerced toward its declared type -- see {@see self::encode()}'s own doc.
Methods
decode()
Decodes `.dxn` text into a value -- every DXN type maps to a native PHP value or a `DXN*` wrapper class, see the project's value-model mapping (`README.md`) for the full picture. Throws {@see DXNError} on malformed input, including a schema violation for any registered `struct` name the text uses.
public
static decode(string $text[, Registry|null $registry = null ]) : mixed
$registry (a Registry built via Schema::compile())
enables schema-backed struct decoding and custom-tag decoding
for any name it knows -- a struct/tag with no matching registry
entry falls back to an opaque DXNStruct/DXNCustomTag, never a
hard failure.
Parameters
- $text : string
- $registry : Registry|null = null
decodeBinary()
Decodes a `.dxnb` binary string into a value -- the same value shapes as {@see self::decode()}. Same `$registry` effect. Throws {@see DXNError} on malformed input, including a missing/invalid envelope (`DX` + version byte) or a schema violation.
public
static decodeBinary(string $bytes[, Registry|null $registry = null ]) : mixed
Parameters
- $bytes : string
- $registry : Registry|null = null
encode()
Encodes a value back to `.dxn` text. Single-line, minimal-whitespace by default; pass `pretty: true` for multi-line, indented output instead (`indent` then sets spaces per nesting level, default 2). Both produce the exact same value on the way back through `decode()` -- `pretty`/`indent` are a rendering choice, never a semantic one. Throws {@see DXNError} for a value with no DXN representation, or that fails schema validation.
public
static encode(mixed $value[, bool $pretty = false ][, int $indent = 2 ][, Registry|null $registry = null ][, bool $validate = true ][, bool $coerce = true ][, string|null $schema = null ]) : string
Automatically validates every DXNStruct or registered
application class instance found anywhere in $value against
its own schema ($registry's compiled schemas) -- pass
validate: false to skip. A $schema name additionally
validates $value itself against that specific schema -- the
one case the automatic walk can't cover on its own, a nameless
top-level bare array or unregistered struct.
$coerce (default true) lets a field whose value doesn't
already match its declared type be coerced toward it first (a
plain float becoming a DXNRational for a :rational field,
say) -- see Coercion's own doc;
this has no Elixir dextrin equivalent. Pass coerce: false
for strict validation with no silent conversion.
Parameters
- $value : mixed
- $pretty : bool = false
- $indent : int = 2
- $registry : Registry|null = null
- $validate : bool = true
- $coerce : bool = true
- $schema : string|null = null
Return values
stringencodeBinary()
Encodes a value to `.dxnb` binary, returning a raw binary string. Same `$registry`/`$validate`/`$coerce`/`$schema` parameters as {@see self::encode()}. Throws {@see DXNError} for a value with no DXN representation, or that fails schema validation.
public
static encodeBinary(mixed $value[, Registry|null $registry = null ][, bool $validate = true ][, bool $coerce = true ][, string|null $schema = null ]) : string
Parameters
- $value : mixed
- $registry : Registry|null = null
- $validate : bool = true
- $coerce : bool = true
- $schema : string|null = null
Return values
string__construct()
private
__construct() : mixed
maybeValidateEncode()
Two independent checks, both applied when requested: the automatic whole-tree walk (every named struct anywhere in `$value`, driven by whether a schema is registered for its name) and, only if `$schema` was given, a check of the (possibly already-coerced) result against that one named schema. Both may return a *transformed* value when `$coerce` (default `true`) lets a mismatched field be coerced toward its declared type -- see {@see self::encode()}'s own doc.
private
static maybeValidateEncode(mixed $value, Registry|null $registry, bool $validate, bool $coerce, string|null $schema) : mixed
Parameters
- $value : mixed
- $registry : Registry|null
- $validate : bool
- $coerce : bool
- $schema : string|null