Ref
in package
$ref resolution expands base inheritance before other composition (SPEC §5).
Resolution supports these input forms: (1) value = a single string OR a list of strings — a list resolves each path in order, then array_merge (later overrides earlier on key clash). (2) plain path 'options.yml' → load YAML, descend by the default detectKey ['properties'] (= take the file's properties only). (3) path-specified '(file.yml).a.b' → regex split, detectKeys = ['a','b', 'properties'] — descend a.b, then descend to properties underneath. (4) relative paths get the basepath '/' prefix; absolute (/-leading) pass through (handled by the FileLoader). (5) the result is recursively processed — nested $ref is expanded.
CRUDUI normalization: $ref is the properties-layer composition entry point. The resolved result is flattened to a single properties map and laid down as the base; $patch overlays it (base first, patch overrides). Unresolved $ref (missing file / bad format / absent detectKey / cycle) is a LOAD ERROR — never valid:true.
Table of Contents
Constants
- PATH_SPEC_RE : mixed = '/^\((?<path>.*?)\)\.(?<keys>.*)$/s'
- The regex that splits '(path).keys' — the path-specified reference form.
Methods
- resolve() : array<string, mixed>
- Resolve a $ref value (string or list of strings) to a single flattened properties map. Each entry is resolved in declaration order and merged (later overrides earlier). Nested $ref inside a resolved doc is expanded recursively. The $visiting set (canonical file keys on the current chain) detects cycles.
- expandNested() : array<string, mixed>
- Expand any $ref (and merge any $patch) sitting INSIDE a resolved properties map, recursively. The resolved base is laid down first, then sibling named keys override it (declaration order: a later plain key overrides an earlier $ref).
- normalizeValue() : array<int, string>
- Normalize the $ref value into a list of path strings (scalar → [scalar]).
- resolveSingle() : array<string, mixed>
- Resolve one $ref path entry, descending detectKeys and expanding nested refs.
- typeName() : string
- JS-style type name for $ref value-type error messages.
Constants
PATH_SPEC_RE
The regex that splits '(path).keys' — the path-specified reference form.
private
mixed
PATH_SPEC_RE
= '/^\((?<path>.*?)\)\.(?<keys>.*)$/s'
Methods
resolve()
Resolve a $ref value (string or list of strings) to a single flattened properties map. Each entry is resolved in declaration order and merged (later overrides earlier). Nested $ref inside a resolved doc is expanded recursively. The $visiting set (canonical file keys on the current chain) detects cycles.
public
static resolve(mixed $value, string $basepath, FileLoader $loader[, array<string, bool> $visiting = [] ]) : array<string, mixed>
Parameters
- $value : mixed
- $basepath : string
- $loader : FileLoader
- $visiting : array<string, bool> = []
Return values
array<string, mixed>expandNested()
Expand any $ref (and merge any $patch) sitting INSIDE a resolved properties map, recursively. The resolved base is laid down first, then sibling named keys override it (declaration order: a later plain key overrides an earlier $ref).
private
static expandNested(array<string, mixed> $node, string $basepath, FileLoader $loader, array<string, bool> $visiting) : array<string, mixed>
Parameters
- $node : array<string, mixed>
- $basepath : string
- $loader : FileLoader
- $visiting : array<string, bool>
Return values
array<string, mixed>normalizeValue()
Normalize the $ref value into a list of path strings (scalar → [scalar]).
private
static normalizeValue(mixed $value) : array<int, string>
Parameters
- $value : mixed
Return values
array<int, string>resolveSingle()
Resolve one $ref path entry, descending detectKeys and expanding nested refs.
private
static resolveSingle(string $rawPath, string $basepath, FileLoader $loader, array<string, bool> $visiting) : array<string, mixed>
Parameters
- $rawPath : string
- $basepath : string
- $loader : FileLoader
- $visiting : array<string, bool>
Return values
array<string, mixed>typeName()
JS-style type name for $ref value-type error messages.
private
static typeName(mixed $v) : string
Parameters
- $v : mixed