README

A DOM-like API for working with JSON data, including an RFC 6901 JSON pointer implementation with the draft relative JSON pointer extension.

Status

API

Document

final class \DaveRandom\Jom\Document
    implements \JsonSerializable
{
    /**
     * Create a Document instance from a JSON string, forwarding arguments to json_encode().
     *
     * @throws ParseFailureException when the supplied string cannot be parsed as JSON.
     * @throws DocumentTreeCreationFailedException when a document tree cannot be built from the parsed data.
     */
    public static Document parse(string $json, int $depthLimit = 512, int $options = 0);

    /**
     * Create a Document instance from a PHP value.
     *
     * @throws DocumentTreeCreationFailedException when a document tree cannot be built from the supplied data.
     */
    public static Document createFromValue($value);

    /**
     * Returns the root node of the document, or NULL if the document is empty.
     */
    public ?Node getRootNode();

    /**
     * Evaluate a JSON pointer against the document tree.
     *
     * @throws InvalidPointerException when the supplied pointer string is invalid
     * @throws PointerEvaluationFailureException when the pointer does not indicate an existing node
     * @throws InvalidSubjectNodeException when the $base node is not part of the document
     */
    public Node|int|string evaluatePointer(Pointer|string $pointer, Node $base = null);
}

Node

/**
 * NOTE: Classes inheriting from Node that are not provided by this library will result in undefined behaviour.
 */
abstract class \DaveRandom\Jom\Node
    implements \JsonSerializable
{
    /**
     * Create a Node instance from a PHP value.
     *
     * @throws InvalidNodeValueException when a Node cannot be built from the supplied data.
     */
    public static Node createFromValue($value);

    /**
     * Returns the parent node of this node, or NULL if this is the root node or the node is not present in the
     * owning document.
     */
    public ?Node getParent();

    /**
     * Returns the next sibling node of this node, or NULL if the node does not have a following sibling node.
     */
    public ?Node getPreviousSibling();

    /**
     * Returns the previous sibling node of this node, or NULL if the node does not have a preceding sibling node.
     */
    public ?Node getNextSibling();

    /**
     * Returns TRUE if this node has child nodes, otherwise FALSE.
     */
    public bool hasChildren();

    /**
     * Returns the first child node of this node, or NULL if the node does not have any child nodes.
     */
    public ?Node getFirstChild();

    /**
     * Returns the last child node of this node, or NULL if the node does not have any child nodes.
     */
    public ?Node getLastChild();

    /**
     * Returns the Document object that owns this node.
     */
    public ?Document getOwnerDocument();

    /**
     * Get a JSON pointer for this node's position in the document. If the $base node is supplied, get a relative
     * pointer.
     *
     * @throws InvalidSubjectNodeException when the $base node is invalid
     */
    public Pointer getPointer(Node $base = null);

    /**
     * Returns the key of this node within its parent node, or NULL if this is the root node of the document.
     */
    public string|int|null getKey();

    /**
     * Returns the data represented by this node as the appropriate PHP type.
     */
    public mixed getValue();
}

NullNode

final class \DaveRandom\Jom\NullNode extends \DaveRandom\Jom\Node
{
    /**
     * Create a new NULL value node owned by the supplied document.
     */
    public __construct(?Document $ownerDocument = null);
}

BooleanNode

final class \DaveRandom\Jom\BooleanNode extends \DaveRandom\Jom\Node
{
    /**
     * Create a new boolean value node owned by the supplied document.
     */
    public __construct(?bool $value = false, ?Document $ownerDocument = null);

    /**
     * Set the value of this node
     */
    public void setValue(bool $value);
}

NumberNode

final class \DaveRandom\Jom\NumberNode extends \DaveRandom\Jom\Node
{
    /**
     * Create a new number value node owned by the supplied document.
     */
    public __construct(int|float|null $value = 0, ?Document $ownerDocument = null);

    /**
     * Set the value of this node
     */
    public void setValue(int|float $value);
}

StringNode

final class \DaveRandom\Jom\StringNode extends \DaveRandom\Jom\Node
{
    /**
     * Create a new string value node owned by the supplied document.
     */
    public __construct(?string $value = "", ?Document $ownerDocument = null);

    /**
     * Set the value of this node
     */
    public void setValue(string $value);
}

VectorNode

/**
 * NOTE: Classes inheriting from VectorNode that are not provided by this library will result in undefined
 * behaviour.
 */
abstract class \DaveRandom\Jom\VectorNode extends \DaveRandom\Jom\Node 
    implements \Countable, \IteratorAggregate, \ArrayAccess
{
    /**
     * Returns the data represented by this node as an array.
     */
    public array toArray();
    
    /**
     * Remove all child nodes.
     */
    public void clear();
}

ArrayNode

final class \DaveRandom\Jom\ArrayNode extends \DaveRandom\Jom\VectorNode
{
    /**
     * Create a new array node owned by the supplied document.
     */
    public __construct(Node[] $values = null, ?Document $ownerDocument = null);

    /**
     * Append one or more nodes to the array.
     *
     * @throws EmptySubjectNodeListException when no nodes are supplied 
     * @throws InvalidSubjectNodeException when one of the supplied nodes is invalid.
     * @throws WriteOperationForbiddenException when there is an active iterator for the array.
     */
    public void push(Node ...$nodes);

    /**
     * Remove the last node from the array, if any, and return it.
     *
     * @throws WriteOperationForbiddenException when there is an active iterator for the array.
     */
    public ?Node pop();

    /**
     * Prepend one or more nodes to the array.
     *
     * @throws EmptySubjectNodeListException when no nodes are supplied 
     * @throws InvalidSubjectNodeException when one of the supplied nodes is invalid.
     * @throws WriteOperationForbiddenException when there is an active iterator for the array.
     */
    public void unshift(Node ...$nodes);

    /**
     * Remove the first node from the array, if any, and return it.
     *
     * @throws WriteOperationForbiddenException when there is an active iterator for the array.
     */
    public ?Node shift();

    /**
     * Insert a new node before the supplied reference node. If $beforeNode is NULL it is equivalent to push().
     *
     * @throws InvalidSubjectNodeException when $node is invalid.
     * @throws InvalidReferenceNodeException when $beforeNode is not a member of the array
     * @throws WriteOperationForbiddenException when there is an active iterator for the array.
     */
    public void insert(Node $node, ?Node $beforeNode);

    /**
     * Replace an existing node object or the node at the supplied index with a new node.
     *
     * @throws InvalidSubjectNodeException when $newNode is invalid.
     * @throws InvalidReferenceNodeException when $nodeOrIndex is not a member of the array
     * @throws WriteOperationForbiddenException when there is an active iterator for the array.
     */
    public void replace(Node|int $nodeOrIndex, Node $newNode);

    /**
     * Remove the supplied node from the array.
     *
     * @throws WriteOperationForbiddenException when there is an active iterator for the array.
     * @throws InvalidSubjectNodeException when $node is not a member of the array.
     */
    public void remove(Node $node);
}

ObjectNode

final class \DaveRandom\Jom\ObjectNode extends \DaveRandom\Jom\VectorNode
{
    /**
     * Create a new array node owned by the supplied document.
     */
    public __construct(Node[] $properties = null, ?Document $ownerDocument = null);

    /**
     * Returns a list of the object's property names.
     */
    public string[] getPropertyNames();

    /**
     * Returns TRUE if the object has a property with the supplied name, otherwise FALSE.
     */
    public bool hasProperty(string $name);

    /**
     * Get the value node associated with the supplied property name.
     *
     * @throws InvalidKeyException when the property does not exist.
     */
    public Node getProperty(string $name);

    /**
     * Set the value node associated with the supplied property name.
     *
     * @throws InvalidSubjectNodeException when $value is invalid.
     * @throws WriteOperationForbiddenException when there is an active iterator for the array.
     */
    public void setProperty(string $name, Node $value);

    /**
     * Remove the supplied property.
     *
     * @throws InvalidSubjectNodeException when $nodeOrName is a Node that is not a property of the object.
     * @throws InvalidKeyException when $nodeOrName is the name of a property that does not exist.
     * @throws WriteOperationForbiddenException when there is an active iterator for the array.
     */
    public void removeProperty(Node|string $nodeOrName);
}

Exception Hierarchy

\Exception
  └ \DaveRandom\Jom\Exceptions\Exception Ⓐ
      ├ \DaveRandom\Jom\Exceptions\DocumentTreeCreationFailedException Ⓕ
      ├ \DaveRandom\Jom\Exceptions\InvalidNodeValueException Ⓕ
      ├ \DaveRandom\Jom\Exceptions\InvalidOperationException Ⓐ
      │   ├ \DaveRandom\Jom\Exceptions\EmptySubjectNodeListException Ⓕ
      │   ├ \DaveRandom\Jom\Exceptions\InvalidKeyException Ⓕ
      │   ├ \DaveRandom\Jom\Exceptions\InvalidReferenceNodeException Ⓕ
      │   ├ \DaveRandom\Jom\Exceptions\InvalidSubjectNodeException Ⓕ
      │   └ \DaveRandom\Jom\Exceptions\WriteOperationForbiddenException Ⓕ
      ├ \DaveRandom\Jom\Exceptions\InvalidPointerException Ⓕ
      ├ \DaveRandom\Jom\Exceptions\ParseFailureException Ⓕ
      └ \DaveRandom\Jom\Exceptions\PointerEvaluationFailureException Ⓕ