JsonReader API

Contents

• The JsonReader Class
  • Constants
  • Methods
    • init()
    • json()
    • open()
    • psr7Stream()
    • stream()
    • type()
    • name()
    • value()
    • depth()
    • next()
    • read()
    • close()
• Exceptions
  • Hierarchy

The JsonReader Class

use pcrov\JsonReader\JsonReader;

Constants

Node types:

JsonReader::NONE
JsonReader::STRING
JsonReader::NUMBER
JsonReader::BOOL
JsonReader::NULL
JsonReader::ARRAY
JsonReader::END_ARRAY
JsonReader::OBJECT
JsonReader::END_OBJECT

Options

JsonReader::FLOATS_AS_STRINGS

Methods

---

__construct(int $options = 0)

Accepts a bit field of options. Currently only JsonReader::FLOATS_AS_STRINGS is supported.

---

init(Parser $parser): void

Initializes the reader with the given parser.

You do not need to call this if you're using one of json(), open(), psr7Stream(), or stream() methods. It's intended to be used with manual initialization of the parser, et al., in cases where custom components are required.

---

json(string $json): void

Initializes the reader with the given JSON string.

---

open(string $uri): void

Initializes the reader with the given local or remote file URI.

Throws an IOException if the given URI is not readable.

---

psr7Stream(\Psr\Http\Message\StreamInterface $stream): void

Initializes the reader with the given PSR-7 stream.

Throws an IOException if the given stream is not readable.

---

stream(resource $stream): void

Initializes the reader with the given stream resource such as that returned by fopen().

Throws an InvalidArgumentException if the given resource is not a valid stream. Throws an IOException if the given stream resource is not readable.

---

type(): string

Returns the type of the current node, one of the JsonReader node constants.

---

name(): string|null

Returns the name, if any, of the current node - i.e. the property name of an object member.

---

value(): mixed

Returns the value of the current node.

For array and object nodes this will be evaluated on demand - their trees built and returned in their entirety. (Note that this means the object or array will have to be parsed and built in memory at once, so if you attempt this at the root of the document you're losing all benefits this library has over json_decode(). Nodes parsed in this way remain cached until they're read past.)

Objects will be returned as arrays with strings for keys. Trying to return stdClass objects would gain nothing but exposure to edge cases where valid JSON produces property names that are not allowed in PHP objects (e.g. "" or "\u0000".)

If JsonReader::FLOATS_AS_STRINGS was given to the constructor, floats will be returned as their original strings. This includes any JSON number with a decimal point or exponent, as well as those above PHP_INT_MAX or below PHP_INT_MIN. The JSON specification places no limits on the range or precision of numbers, and returning floats as strings allows you to handle them with BC Math or GMP as needed.

---

depth(): int

Returns the depth of the current node in the tree, starting at 0.

---

next(string $name = null): bool

Move to the next node, skipping subtrees. If a name is given it will continue until a node of that name is reached or the document ends.

Throws an Exception if called before data has been initialized.

---

read(string $name = null): bool

Move to the next node. If a name is given it will continue until a node of that name is reached or the document ends.

Throws an Exception if called before data has been initialized.

---

close(): void

Closes the parser. Note that a file handle passed to stream() will not be closed by this method. That is left to the caller.

---

Exceptions

All exceptions used are or extend pcrov\JsonReader\Exception.

Hierarchy

pcrov\JsonReader\Exception extends \Exception
pcrov\JsonReader\InvalidArgumentException extends pcrov\JsonReader\Exception
pcrov\JsonReader\InputStream\IOException extends pcrov\JsonReader\Exception
pcrov\JsonReader\Parser\ParseException extends pcrov\JsonReader\Exception