Download the PHP package dmitrijs-brujevs/data-object without Composer

DataObject

A lightweight, path-based in-memory data container for PHP 8.2+.

Stores data in a nested array and provides access via slash-separated node paths. No dependencies. No magic beyond what is documented.

Why this library?

• You receive config, API responses, or form data as nested arrays and want clean, readable access without $data['user']['address']['city'] ?? null chains
• You want dot/slash-path notation with isset-safe existence checks
• You need a minimal, subclassable value object with no framework coupling

Requirements

• PHP 8.2+
• ext-json

Installation

Quick Start

Creating an Instance

Use the explicit factory methods when the input format is known:

The constructor also accepts all three formats via auto-detection:

An InvalidArgumentException is thrown if the string is neither valid JSON nor a serialized array.

Path Notation

Each segment of a path corresponds to a key in the nested structure. The default delimiter is /, customisable per instance.

API Reference

get(string $node = ''): mixed

Returns the value at the given path.

• Nested array → returned as a new DataObject instance (same concrete class)
• Missing path → returns null
• No arguments → returns $this (root)

null vs missing: get() returns null for both a missing path and an explicit null value. Use has() to distinguish them, or use getOrDefault().

getOrDefault(string $node, mixed $default = null): mixed

Returns the value at the given path, or $default if the node does not exist.

Unlike get(), this correctly distinguishes between a missing node and an explicit null value:

has(string $node): bool

Returns true if the node exists, regardless of its value. Uses array_key_exists semantics.

is(string $node, mixed $value): bool

Strict equality check (===). Returns false if the node does not exist.

Note: is('missing', null) returns false (changed in 2.1.0 — previously returned true). Use has() or getOrDefault() if the old behaviour was relied upon.

set(string|int $node, mixed $value): static

Sets a value at the given path. Intermediate nodes are created automatically. If an intermediate node holds a non-array value, it is replaced with an array. Returns $this for fluent chaining.

add(array $array, string $node = ''): static

Recursively merges a nested array into the object. Existing values at the same paths are overwritten. Empty arrays are stored as-is — get() on that path returns an empty DataObject.

delete(string $node): static

Removes the value at the given path. Only the final segment is removed; parent nodes and siblings remain intact. No-op for non-existent paths.

toArray(): array

Returns the internal storage as a plain nested PHP array.

toJson(int $flags, int $depth): string

Returns the data encoded as a JSON string. Default flags: JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES.

serialize(): string

Returns the data as a PHP serialized string.

Magic camelCase Methods

Any method prefixed with get, set, has, is, or delete is resolved by __call() at runtime. The name is split on uppercase letters and joined with the delimiter to form a path.

Unknown prefixes throw BadMethodCallException (changed in 2.1.0 — previously returned null).

Limitations:

• Consecutive uppercase letters are split per character: getURLPath() → get('u/r/l/path'). Use explicit path strings for such keys.
• Multi-word method names (getOrDefault) cannot be dispatched via magic — the parser only recognises single-word prefixes.

Iteration

DataObject implements Iterator. Nested arrays are automatically wrapped in DataObject instances at each level.

Custom Delimiter

Subclassing

DataObject is designed to be subclassed. All factory methods and internal wrapping use new static(), so nested arrays and iterator values are wrapped in the concrete subclass.

Public method overrides in subclasses take full precedence — PHP routes them directly without going through __call().

Security — Serialized Input

fromSerialized() and the constructor's auto-detection both use unserialize($data, ['allowed_classes' => false]).

This means:

• No PHP objects are instantiated during deserialization — gadget-chain attacks are blocked
• Only arrays are accepted; anything else throws InvalidArgumentException
• PHP warnings from malformed strings are caught via a temporary error handler, not @

Only pass serialized data from sources you control. Even with allowed_classes = false, deserializing untrusted user input is not recommended practice.

Running Locally

License

MIT