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: the top-level collection one entry per line, a nested one on one line when it fits (`indent` then sets spaces per nesting level, default 2, and `width` the columns that line must fit in, default 80). Both produce the exact same value on the way back through `decode()` -- `pretty`/`indent`/`width` 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`/`$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 result against that one named schema.
- strictly() : Registry|null
- `$registry` marked strict when `$strict` is given -- a strict decode refuses extra fields on schema-backed structs (DXNS.md §7).
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 ][, bool|null $strict = 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
- $strict : bool|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 ][, bool|null $strict = null ]) : mixed
Parameters
- $bytes : string
- $registry : Registry|null = null
- $strict : bool|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: the top-level collection one entry per line, a nested one on one line when it fits (`indent` then sets spaces per nesting level, default 2, and `width` the columns that line must fit in, default 80). Both produce the exact same value on the way back through `decode()` -- `pretty`/`indent`/`width` 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 ][, string|null $schema = null ][, int $width = 80 ]) : 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.
Nothing is converted to make a value match its declared type
(DXNS.md §7): a host value always means the same DXN type,
schema or not, so a float for a :rational field is refused
rather than turned into a DXNRational. Use the DXN* classes to
say which type a value is.
Parameters
- $value : mixed
- $pretty : bool = false
- $indent : int = 2
- $registry : Registry|null = null
- $validate : bool = true
- $schema : string|null = null
- $width : int = 80
Return values
stringencodeBinary()
Encodes a value to `.dxnb` binary, returning a raw binary string. Same `$registry`/`$validate`/`$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 ][, string|null $schema = null ]) : string
Parameters
- $value : mixed
- $registry : Registry|null = null
- $validate : 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 result against that one named schema.
private
static maybeValidateEncode(mixed $value, Registry|null $registry, bool $validate, string|null $schema) : mixed
Parameters
- $value : mixed
- $registry : Registry|null
- $validate : bool
- $schema : string|null
strictly()
`$registry` marked strict when `$strict` is given -- a strict decode refuses extra fields on schema-backed structs (DXNS.md §7).
private
static strictly(Registry|null $registry, bool|null $strict) : Registry|null
Parameters
- $registry : Registry|null
- $strict : bool|null