daverandom / jom
A DOM-like API for working for JSON
dev-master
2018-08-23 19:05 UTC
Requires
- php: >=7.2
- ext-ctype: *
- ext-json: *
- daverandom/exceptional-json: ^1.0
Requires (Dev)
- phpunit/phpunit: ^6
This package is auto-updated.
Last update: 2024-10-25 08:35:29 UTC
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 Ⓕ