JsonMachine

https://github.com/halaxa/json-machine
Admin
A memory-efficient PHP library for parsing large JSON files or streams incrementally, offering...
Tokens:59,147
Snippets:437
Trust Score:6.6
License:Apache-2.0
Update:4 days ago
Show doc for...
Tokens:
Raw
### Install json-machine via Composer

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Use Composer to install the halaxa/json-machine package. This is the standard installation method for PHP projects using Composer.

```bash
composer require halaxa/json-machine
```

--------------------------------

### Using TokensWithDebugging with Items facade

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/TokensWithDebugging.md

Example of enabling debug mode via Items::fromFile to get position information during iteration.

```php
use JsonMachine\Items;

$items = Items::fromFile('big.json', ['debug' => true]);
foreach ($items as $key => $value) {
    // tokens now carry position info; getPosition() reflects byte progress
    $progress = $items->getPosition();
}
```

--------------------------------

### Using getMatchedJsonPointer and getCurrentJsonPointer

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Shows how to use getMatchedJsonPointer to check the matched pointer and getCurrentJsonPointer to get the concrete path. The example uses a pointer '/results/-/color' and iterates over fruits.

```php
$fruits = Items::fromFile('fruitsArray.json', ['pointer' => '/results/-/color']);

foreach ($fruits as $key => $value) {
    if ($fruits->getMatchedJsonPointer() === '/results/-/color') {
        $actual = $fruits->getCurrentJsonPointer(); // '/results/0/color', '/results/1/color', ...
    }
}
```

--------------------------------

### Creating ItemsOptions instance

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ItemsOptions.md

Shows how to instantiate ItemsOptions with pointer and debug options, then access the decoder and get the validated array.

```php
use JsonMachine\ItemsOptions;

$options = new ItemsOptions(['pointer' => '/results', 'debug' => true]);
$options['decoder'];       // ExtJsonDecoder instance (default)
$options->toArray();        // validated option map
```

--------------------------------

### Using getPosition to show progress

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Shows how to use getPosition with debug enabled to display progress as a percentage. The example reads a file and calculates progress based on file size.

```php
$fileSize = filesize('fruits.json');
$fruits = Items::fromFile('fruits.json', ['debug' => true]);

foreach ($fruits as $name => $data) {
    echo 'Progress: ' . intval($fruits->getPosition() / $fileSize * 100) . '%' . PHP_EOL;
}
```

--------------------------------

### StringChunks usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Chunks.md

Creates a Tokens instance from a StringChunks adapter for an in-memory JSON string.

```php
use JsonMachine\StringChunks;
use JsonMachine\Tokens;

$json = '{"apple":{"color":"red"},"pear":{"color":"yellow"}}';
$tokens = new Tokens(new StringChunks($json, 1024));
```

--------------------------------

### Usage with Items facade

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ItemsOptions.md

Shows how to use ItemsOptions with Items::fromFile, passing the validated options array. The example uses pointer array, PassThruDecoder, and debug false.

```php
use JsonMachine\Items;
use JsonMachine\ItemsOptions;
use JsonMachine\JsonDecoder\PassThruDecoder;

$options = new ItemsOptions([
    'pointer' => ['/berries', '/citruses'],
    'decoder' => new PassThruDecoder(),
    'debug'   => false,
]);

$items = Items::fromFile(
    'fruits.json',
    $options->toArray()   // or pass the raw array directly
);
foreach ($items as $key => $value) {
    // ...
}
```

--------------------------------

### Array access example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/RecursiveItems.md

Shows array syntax for accessing nested JSON items; must be echoed to consume the value.

```php
$users[0]['friends'][1]['username'] === 'friend2'; // echo it to consume
```

--------------------------------

### RecursiveItems usage example with fromFile and toArray

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/RecursiveItems.md

Example showing recursive iteration: yields RecursiveItems for dicts/lists, uses array-access syntax for nested items, and materializes small parts with toArray().

```php
use JsonMachine\RecursiveItems;

$users = RecursiveItems::fromFile('users.json');
foreach ($users as $user) {                 // $user is RecursiveItems (a dict)
    foreach ($user['friends'] as $friend) { // array-access syntax
        $friendArray = $friend->toArray();  // materialize a small part
        echo $friendArray['username'] . "\n";
    }
}
```

--------------------------------

### fromFile usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Opens the file read-only during iteration (16 KiB chunks via FileChunks) and closes it when iteration finishes or fails. Iterating over a large file keeps a constant memory footprint regardless of file size.

```php
$users = Items::fromFile('500MB-users.json');
foreach ($users as $id => $user) {
    // constant memory footprint regardless of file size
}
```

--------------------------------

### fromStream usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Consumes 8 KiB chunks from the stream. Invalid stream resources raise InvalidArgumentException from StreamChunks. The example shows opening an HTTP stream and optionally converting a Guzzle stream.

```php
$jsonStream = fopen('https://api.example.com/users', 'r');
// or convert a Guzzle stream: \GuzzleHttp\Psr7\StreamWrapper::getResource($response->getBody())
$users = Items::fromStream($jsonStream, ['pointer' => '/users']);
foreach ($users as $user) {
    // process user
}
```

--------------------------------

### FileChunks usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Chunks.md

Iterates over a JSON file in chunks. Each chunk is a raw string up to 16 KiB.

```php
use JsonMachine\FileChunks;

foreach (new FileChunks('data.json') as $chunk) {
    // $chunk is a raw string, up to 16 KiB
}
```

--------------------------------

### advanceToKey usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/RecursiveItems.md

Shows chaining advanceToKey calls to navigate nested JSON structures. The method is forward-only, so previously visited keys cannot be re-accessed.

```php
$user = $users->advanceToKey(0);            // first user on the main level
$friends = $user->advanceToKey('friends');  // its 'friends' dict/list
echo $friends->advanceToKey(1)->advanceToKey('username'); // 'friend2'
```

--------------------------------

### Usage example: lexing JSON chunks into tokens

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Tokens.md

Creates a Tokens instance from an array of JSON string chunks and converts the yielded tokens to an array. The output shows whitespace stripped and structure preserved.

```php
use JsonMachine\Tokens;

$tokens = new Tokens(['{"a"', ': 1}']);
$list = iterator_to_array($tokens);
// ['{', '"a"', ':', '1', '}']  (whitespace stripped, structure preserved)
```

--------------------------------

### toIterator() usage examples

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/FunctionsAndAutoloading.md

Shows converting an ArrayIterator (already an Iterator) and an ArrayObject (dereferenced Aggregate) to an Iterator.

```php
$iterator = toIterator(new ArrayIterator([1, 2, 3])); // already an Iterator
$iterator = toIterator(new ArrayObject([1, 2, 3]));    // dereferenced Aggregate
```

--------------------------------

### Iterate over multiple subtrees with Items::fromFile and pointer array

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Uses JsonMachine\Items::fromFile with the 'pointer' option set to an array of JSON Pointers ['/berries', '/citruses'] to iterate over all items in both subtrees. Items are yielded in document order regardless of pointer order; getCurrentJsonPointer() returns the pointer of the current item. The example shows the expected values and pointers for each of the four iterations.

```php
<?php

use \JsonMachine\Items;

$fruits = Items::fromFile('fruits.json', [
    'pointer' => ['/berries', '/citruses']
]);

foreach ($fruits as $key => $value) {
    // 1st iteration:
    $value == ["name" => "strawberry", "color" => "red"];
    $fruits->getCurrentJsonPointer() == '/berries';

    // 2nd iteration:
    $value == ["name" => "raspberry", "color" => "red"];
    $fruits->getCurrentJsonPointer() == '/berries';

    // 3rd iteration:
    $value == ["name" => "orange", "color" => "orange"];
    $fruits->getCurrentJsonPointer() == '/citruses';

    // 4th iteration:
    $value == ["name" => "lime", "color" => "green"];
    $fruits->getCurrentJsonPointer() == '/citruses';
}
```

--------------------------------

### Iterating tokens with position tracking

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/TokensWithDebugging.md

Example usage of TokensWithDebugging to iterate over JSON tokens and print each token with its byte position and line number.

```php
use JsonMachine\TokensWithDebugging;

$tokens = new TokensWithDebugging(["{\n  \"a\": 1\n}"]);
foreach ($tokens as $token) {
    printf("%-4s @%d:%d\n", $token, $tokens->getPosition(), $tokens->getLine());
}
```

--------------------------------

### fromString usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Parses an in-memory JSON string with Items::fromString. Chunked by StringChunks (8192 bytes per chunk). Decoded values are objects by default; pass new ExtJsonDecoder(true) in decoder to get arrays.

```php
$fruits = Items::fromString('{"apple":{"color":"red"},"pear":{"color":"yellow"}}');

foreach ($fruits as $name => $data) {
    echo $name . ': ' . $data->color . "\n"; // apple: red / pear: yellow
}
```

--------------------------------

### Example: Resuming iteration with proxy

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ResumableIteratorAggregateProxy.md

Shows that a second iterator_to_array on the proxy yields nothing because the inner generator is exhausted, whereas a plain re-foreach would restart.

```php
use JsonMachine\ResumableIteratorAggregateProxy;
use JsonMachine\StringChunks;

$inner = new StringChunks('{"a": 1, "b": 2}');
$proxy = new ResumableIteratorAggregateProxy($inner);

$first = iterator_to_array($proxy);    // consumed
$second = iterator_to_array($proxy);   // yields nothing (already exhausted) —
                                       // a plain re-foreach of $inner would have restarted
```

--------------------------------

### toArray usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/RecursiveItems.md

Shows converting a friend object to an array. The method moves the internal pointer to the end and can only be called before any items are accessed.

```php
$friendArray = $friend->toArray(); // ['username' => 'friend1', 'e-mail' => 'friend1@example.com']
```

--------------------------------

### fromIterable usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Parses from a custom chunk source, such as a Symfony HttpClient response stream converted to a generator. The example defines a generator function and passes it to Items::fromIterable with a pointer option.

```php
use JsonMachine\Items;

function httpClientChunks($responseStream) {
    foreach ($responseStream as $chunk) {
        yield $chunk->getContent();
    }
}

$jsonChunks = httpClientChunks($client->stream($response));
foreach (Items::fromIterable($jsonChunks, ['pointer' => '/args']) as $key => $value) {
    // ...
}
```

--------------------------------

### StreamChunks usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Chunks.md

Iterates over a stream resource in chunks. Here, reads from php://stdin with a chunk size of 4096 bytes.

```php
use JsonMachine\StreamChunks;

$handle = fopen('php://stdin', 'r');
foreach (new StreamChunks($handle, 4096) as $chunk) {
    // process $chunk
}
```

--------------------------------

### Track parsing progress with debug enabled

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Use Items::getPosition() inside a foreach loop to get the number of processed bytes. Calculate percentage as position / total * 100. Requires the 'debug' option set to true; otherwise getPosition() always returns 0.

```php
<?php

use JsonMachine\Items;

$fileSize = filesize('fruits.json');
$fruits = Items::fromFile('fruits.json', ['debug' => true]);
foreach ($fruits as $name => $data) {
    echo 'Progress: ' . intval($fruits->getPosition() / $fileSize * 100) . ' %'; 
}
```

--------------------------------

### Using ExtJsonDecoder with Items

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/JsonDecoder.md

Example usage: decode objects as PHP arrays by passing a new ExtJsonDecoder(true) to Items::fromFile's decoder option.

```php
use JsonMachine\JsonDecoder\ExtJsonDecoder;
use JsonMachine\Items;

// decode objects as PHP arrays
$items = Items::fromFile('data.json', ['decoder' => new ExtJsonDecoder(true)]);
foreach ($items as $key => $item) { /* $item is an array */ }
```

--------------------------------

### Using ErrorWrappingDecoder with Items::fromFile

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/JsonDecoder.md

Example of skipping malformed JSON items and continuing to process the rest of the document. Requires an inner decoder like ExtJsonDecoder.

```php
use JsonMachine\Items;
use JsonMachine\JsonDecoder\DecodingError;
use JsonMachine\JsonDecoder\ErrorWrappingDecoder;
use JsonMachine\JsonDecoder\ExtJsonDecoder;

$items = Items::fromFile('dirty.json', [
    'decoder' => new ErrorWrappingDecoder(new ExtJsonDecoder()),
]);
foreach ($items as $key => $item) {
    if ($key instanceof DecodingError || $item instanceof DecodingError) {
        // skip this malformed json item and continue with the document
        continue;
    }
    // process healthy item
}
```

--------------------------------

### ValidJsonPointers usage example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ValidJsonPointers.md

Creates a ValidJsonPointers instance with two pointers and calls toArray() to validate and retrieve the normalized list.

```php
use JsonMachine\ValidJsonPointers;

$pointers = new ValidJsonPointers(['/results/-/color', '/meta']);
$validated = $pointers->toArray(); // ['/results/-/color', '/meta']
```

--------------------------------

### Simplified RecursiveItems with advanceToKey and toArray

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Uses the array-like syntax $user['friends'] as an alias for $user->advanceToKey('friends') to directly access a key without a loop. Calls to toArray() materialize the RecursiveItems into a plain PHP array. This example simplifies the previous nested iteration.

```php
<?php

use JsonMachine\RecursiveItems

$users = RecursiveItems::fromFile('users.json');
foreach ($users as $user) {
    /** @var $user RecursiveItems */
    foreach ($user['friends'] as $friend) { // or $user->advanceToKey('friends')
        /** @var $friend RecursiveItems */
        $friendArray = $friend->toArray();
        $friendArray['username'] === 'friend1';
    }
}
```

--------------------------------

### Configuration error handling with InvalidArgumentException

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/errors.md

Catches invalid configuration options. The example shows a typo 'poiner' which triggers InvalidArgumentException with a message suggesting the correct option 'pointer'.

```php
use JsonMachine\Items;
use JsonMachine\Exception\InvalidArgumentException;

try {
    $items = Items::fromFile('data.json', ['poiner' => '/results']); // typo
} catch (InvalidArgumentException $e) {
    echo $e->getMessage(); // "Option 'poiner' does not exist. Did you mean 'pointer'?"
}
```

--------------------------------

### Custom UpperCaseDecoder implementing ItemDecoder

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/JsonDecoder.md

Shows how to implement a custom decoder when json_decode is not sufficient. The example checks if the JSON value is a string and returns an InvalidResult otherwise, or a ValidResult with the uppercased decoded string.

```php
use JsonMachine\JsonDecoder\ItemDecoder;
use JsonMachine\JsonDecoder\ValidResult;
use JsonMachine\JsonDecoder\InvalidResult;

class UpperCaseDecoder implements ItemDecoder
{
    public function decode($jsonValue)
    {
        if (substr($jsonValue, 0, 1) !== '"') {
            return new InvalidResult("Expected a JSON string, got $jsonValue");
        }
        return new ValidResult(strtoupper(json_decode($jsonValue)));
    }
}
```

--------------------------------

### FileChunks::__construct

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Chunks.md

Creates a FileChunks instance to read a file in fixed-size chunks. The file is opened lazily when iteration starts.

```APIDOC
## FileChunks::__construct

### Description
Creates a FileChunks instance to read a file in fixed-size chunks. The file is opened lazily when iteration starts.

### Method
Constructor

### Signature
```php
public function __construct($fileName, $chunkSize = 1024 * 16)
```

### Parameters
- **$fileName** (string) - Required - Path of the JSON file to read.
- **$chunkSize** (int) - Optional - Maximum bytes read per `fread` call. Default: `1024 * 16` (16384).

### Example
```php
use JsonMachine\FileChunks;

$chunks = new FileChunks('data.json');
```
```

--------------------------------

### Items::fromFile with debug option

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/configuration.md

Enables progress tracking with real byte positions, line, and column information. Useful for monitoring iteration progress and error reporting.

```APIDOC
## [PHP] Items::fromFile with debug option

### Description
Enables progress tracking with real byte positions, line, and column information. Useful for monitoring iteration progress and error reporting.

### Method
PHP static factory method

### Endpoint
Items::fromFile(string $filename, array $options)

### Parameters
#### Options
- **debug** (bool) - Optional - When true, enables progress tracking. The tokenizer becomes TokensWithDebugging, and Items::getPosition() / RecursiveItems::getPosition() report real byte offsets. SyntaxErrorException messages include real byte position. Slight performance cost.

### Request Example
```php
$fileSize = filesize('fruits.json');
$fruits = Items::fromFile('fruits.json', ['debug' => true]);
foreach ($fruits as $name => $data) {
    echo 'Progress: ' . intval($fruits->getPosition() / $fileSize * 100) . '%' . PHP_EOL;
}
```

### Response
Returns an Items instance with progress tracking enabled.
```

--------------------------------

### Using debug option to track progress

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/configuration.md

Enables progress tracking with real byte positions. getPosition() reports actual byte offsets, and SyntaxErrorException messages include the real byte position. Slight performance cost vs. default.

```php
$fileSize = filesize('fruits.json');
$fruits = Items::fromFile('fruits.json', ['debug' => true]);
foreach ($fruits as $name => $data) {
    echo 'Progress: ' . intval($fruits->getPosition() / $fileSize * 100) . '%' . PHP_EOL;
}
```

--------------------------------

### fruits.json sample data with multiple subtrees

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Sample JSON document containing two subtrees, 'berries' and 'citruses', used to demonstrate parsing multiple subtrees with multiple JSON Pointers. The file is named fruits.json.

```json
// fruits.json
{
    "lastModified": "2012-12-12",
    "berries": [
        {
          "name": "strawberry", // not a berry, but whatever ...
          "color": "red"
        },
        {
          "name": "raspberry", // the same ...
          "color": "red"
        }
    ],
    "citruses": [
      {
          "name": "orange",
          "color": "orange"
      },
      {
          "name": "lime",
          "color": "green"
      }
    ]
}
```

--------------------------------

### Instantiate Parser with Tokens and ExtJsonDecoder

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Parser.md

Creates a Parser over a chunk iterable, targeting JSON Pointer '/a'. Iterating yields key-value pairs where key is 'a' and value is 1.

```php
use JsonMachine\Parser;
use JsonMachine\Tokens;
use JsonMachine\JsonDecoder\ExtJsonDecoder;

$parser = new Parser(
    new Tokens(['{"a":1,"b":2}']),   // chunk iterable
    '/a',
    new ExtJsonDecoder()
);
foreach ($parser as $key => $value) {
    // $key === 'a', $value === 1
}
```

--------------------------------

### Register autoloader without Composer

Source: https://github.com/halaxa/json-machine/blob/master/README.md

If you are not using Composer, clone or download the repository and register the provided autoloader in your bootstrap file. Replace '/path/to/json-machine/src/autoloader.php' with the actual path to the autoloader file.

```php
spl_autoload_register(require '/path/to/json-machine/src/autoloader.php');
```

--------------------------------

### Using pointer option with Items::fromFile

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/configuration.md

Configures the JSON pointer(s) to extract specific parts of a JSON document. A pointer that matches nothing triggers PathNotFoundException at end of iteration, and multiple pointers must not intersect.

```php
$items = Items::fromFile('fruits.json', ['pointer' => '/results']);
$items = Items::fromFile('fruitsArray.json', ['pointer' => '/results/-/color']);
$items = Items::fromFile('fruits.json', ['pointer' => ['/berries', '/citruses']]);
```

--------------------------------

### Broad catch for all JSON Machine errors

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/errors.md

Recommended catch-all for any error from JSON Machine. Wrap iteration in try/catch with JsonMachineException to handle all library errors.

```php
use JsonMachine\Exception\JsonMachineException;

try {
    foreach ($items as $key => $value) {
        // ...
    }
} catch (JsonMachineException $e) {
    // any error from JSON Machine
}
```

--------------------------------

### Constructor signature for ItemsOptions

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ItemsOptions.md

Defines the constructor that accepts an options array. Throws InvalidArgumentException for unknown option names or type errors.

```php
public function __construct(array $options = [])
```

--------------------------------

### ExtJsonDecoder instance static method

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/JsonDecoder.md

Returns a process-wide shared ExtJsonDecoder (lazily created singleton) with default constructor arguments only.

```php
public static function instance(): self
```

--------------------------------

### fromFile method signature

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Declares the static factory that opens a readable JSON file. Accepts the same $options array and throws InvalidArgumentException on invalid options or pointer values.

```php
public static function fromFile($file, array $options = []): self
```

--------------------------------

### Shortcut to get scalar value with iterator_to_array

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Uses iterator_to_array to directly access the scalar value by its key. Works for any scalar value and supports array indices in the JSON Pointer.

```php
<?php

use \JsonMachine\Items;

$fruits = Items::fromFile('fruits.json', ['pointer' => '/lastModified']);
$lastModified = iterator_to_array($fruits)['lastModified'];

```

--------------------------------

### Items::fromFile with pointer option

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/configuration.md

Configures the JSON pointer to select which parts of the document to iterate over. Supports object, array, scalar, and nested values, with wildcard and RFC 6901 unescaping.

```APIDOC
## [PHP] Items::fromFile with pointer option

### Description
Configures the JSON pointer to select which parts of the document to iterate over. Supports object, array, scalar, and nested values, with wildcard and RFC 6901 unescaping.

### Method
PHP static factory method

### Endpoint
Items::fromFile(string $filename, array $options)

### Parameters
#### Options
- **pointer** (string|array) - Optional - JSON pointer or array of pointers to select the data to iterate. Must not intersect. If pointer matches nothing, PathNotFoundException is thrown at end of iteration.

### Request Example
```php
$items = Items::fromFile('fruits.json', ['pointer' => '/results']);
$items = Items::fromFile('fruitsArray.json', ['pointer' => '/results/-/color']);
$items = Items::fromFile('fruits.json', ['pointer' => ['/berries', '/citruses']]);
```

### Response
Returns an Items instance for iteration.
```

--------------------------------

### RecursiveItems::fromFile()

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Creates a new RecursiveItems instance from a JSON file. This is the entry point for recursive iteration over JSON data.

```APIDOC
## RecursiveItems::fromFile()

### Description
Creates a new RecursiveItems instance from a JSON file. This is the entry point for recursive iteration over JSON data.

### Method
Static factory method

### Endpoint
`RecursiveItems::fromFile(string $filename)`

### Parameters
- **$filename** (string) - Required - Path to the JSON file.

### Return Value
Returns a new `RecursiveItems` instance.

### Example
```php
$users = RecursiveItems::fromFile('users.json');
```
```

--------------------------------

### ValidJsonPointers invalid and intersecting input example

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ValidJsonPointers.md

Shows how invalid pointer format and intersecting pointers raise InvalidArgumentException. The first pointer has a bad escape, the second intersects with '/a/b'.

```php
use JsonMachine\ValidJsonPointers;
use JsonMachine\Exception\InvalidArgumentException;

try {
    new ValidJsonPointers(['/a~2b'])->toArray();      // bad escape
    new ValidJsonPointers(['/a', '/a/b'])->toArray(); // intersects
} catch (InvalidArgumentException $e) {
    // "Given value '/a~2b' of $jsonPointer is not valid JSON Pointer"
    // or "JSON Pointers must not intersect. At least these two do: '/a', '/a/b'"
}
```

--------------------------------

### defaultOptions static method signature

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ItemsOptions.md

Returns the default option values: pointer as empty string, decoder as new ExtJsonDecoder(), and debug as false.

```php
public static function defaultOptions(): array
```

--------------------------------

### Using PassThruDecoder with Items::fromFile

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/JsonDecoder.md

Shows how to configure Items::fromFile with PassThruDecoder so values and keys are yielded as raw JSON strings. Since 1.0.0 no json_decode call is made; parse the raw JSON yourself as needed.

```php
use JsonMachine\JsonDecoder\PassThruDecoder;
use JsonMachine\Items;

$items = Items::fromFile('data.json', ['decoder' => new PassThruDecoder()]);
foreach ($items as $key => $rawJson) {
    // $rawJson is e.g. '{"color":"red"}' — parse it yourself as needed
}
```

--------------------------------

### Idiomatic foreach usage of Items

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Shows the typical way to iterate over Items. The generator yields key-value pairs as described in getIterator.

```php
foreach ($items as $key => $value) { /* ... */ } // idiomatic
```

--------------------------------

### Wrap decoding errors with ErrorWrappingDecoder

Source: https://github.com/halaxa/json-machine/blob/master/README.md

ErrorWrappingDecoder decorates another decoder and wraps decoding errors inside DecodingError objects, allowing you to skip malformed items instead of dying on SyntaxError exception. The example shows how to handle errors in the foreach loop.

```php
<?php

use JsonMachine\Items;
use JsonMachine\JsonDecoder\DecodingError;
use JsonMachine\JsonDecoder\ErrorWrappingDecoder;
use JsonMachine\JsonDecoder\ExtJsonDecoder;

$items = Items::fromFile('path/to.json', ['decoder' => new ErrorWrappingDecoder(new ExtJsonDecoder())]);
foreach ($items as $key => $item) {
    if ($key instanceof DecodingError || $item instanceof DecodingError) {
        // handle error of this malformed json item
        continue;
    }
    var_dump($key, $item);
}
```

--------------------------------

### Parse a subtree using JSON Pointer '/results'

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Iterates only the 'results' subtree of a JSON document. The pointer option '/results' selects that subtree. Memory usage stays constant because only one item at a time is loaded.

```json
// fruits.json
{
    "results": {
        "apple": {
            "color": "red"
        },
        "pear": {
            "color": "yellow"
        }
    }
}

```

```php
<?php

use \JsonMachine\Items;

$fruits = Items::fromFile('fruits.json', ['pointer' => '/results']);
foreach ($fruits as $name => $data) {
    // The same as above, which means:
    // 1st iteration: $name === "apple" and $data->color === "red"
    // 2nd iteration: $name === "pear" and $data->color === "yellow"
}

```

--------------------------------

### getLine method signature

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/TokensWithDebugging.md

Returns the 1-based line number of the current lexeme.

```php
public function getLine()
```

--------------------------------

### RecursiveItems nested iteration in PHP

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Iterates over users.json with RecursiveItems, descending into the 'friends' field. Each nested list or dict yields another RecursiveItems instance, so only scalar values or RecursiveItems are returned. The example checks that friend fields match expected values. Note that breaking out of a deeper iteration and advancing prevents later iteration of that skipped data.

```php
<?php

use JsonMachine\RecursiveItems

$users = RecursiveItems::fromFile('users.json');
foreach ($users as $user) {
    /** @var $user RecursiveItems */
    foreach ($user as $field => $value) {
        if ($field === 'friends') {
            /** @var $value RecursiveItems */
            foreach ($value as $friend) {
                /** @var $friend RecursiveItems */
                foreach ($friend as $friendField => $friendValue) {
                    $friendField == 'username';
                    $friendValue == 'friend1';
                }
            }
        }
    }
}
```

--------------------------------

### RecursiveItems::fromFile

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/RecursiveItems.md

Static factory to create a RecursiveItems instance from a file. Throws InvalidArgumentException on invalid options/pointers.

```APIDOC
## RecursiveItems::fromFile

### Description
Static factory to create a RecursiveItems instance from a file. Throws InvalidArgumentException on invalid options/pointers.

### Method
Static Factory

### Signature
```php
public static function fromFile($file, array $options = []): self
```

### Parameters
- `$file` (string) - Required - Path to the JSON file.
- `$options` (array) - Optional - Options array, same as Items::fromFile.

### Exceptions
- `JsonMachine\Exception\InvalidArgumentException` - Thrown on invalid options/pointers.

```

--------------------------------

### Constructor signature for Tokens

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Tokens.md

Constructor accepts any iterable yielding raw JSON string chunks. Used to create a Tokens lexer instance.

```php
public function __construct($jsonChunks)
```

--------------------------------

### ItemsOptions::defaultOptions (static)

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ItemsOptions.md

Returns the default option values for pointer, decoder, and debug.

```APIDOC
## ItemsOptions::defaultOptions (static)

### Description
Returns the default option values for pointer, decoder, and debug.

### Method
defaultOptions (static)

### Signature
```php
public static function defaultOptions(): array
```

### Returns
- `array` - The option defaults:
  - `pointer` (string) - Default `''`
  - `decoder` (ExtJsonDecoder) - Default `new ExtJsonDecoder()`
  - `debug` (bool) - Default `false`

### Example
```php
$defaults = ItemsOptions::defaultOptions();
```
```

--------------------------------

### TL;DR: Using Items::fromFile to avoid memory exhaustion

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Shows the recommended way to parse large JSON files with JSON Machine, replacing json_decode which can exhaust memory. The foreach loop processes items one by one with a small memory footprint.

```php
<?php

use \JsonMachine\Items;

// this often causes Allowed Memory Size Exhausted,
// because it loads all the items in the JSON into memory
- $users = json_decode(file_get_contents('500MB-users.json'));

// this has very small memory footprint no matter the file size
// because it loads items into memory one by one
+ $users = Items::fromFile('500MB-users.json');

foreach ($users as $id => $user) {
    // just process $user as usual
    var_dump($user->name);
}
```

--------------------------------

### getJsonPointers method signature

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Returns the configured JSON Pointer(s) as a list. An empty string '' means the document main level.

```php
public function getJsonPointers(): array
```

--------------------------------

### Constructor: __construct

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ResumableIteratorAggregateProxy.md

Creates a proxy that allows resuming iteration of an inner IteratorAggregate. Throws InvalidArgumentException if the argument is not an IteratorAggregate.

```php
public function __construct(\Traversable $iteratorAggregate)
```

--------------------------------

### Items::fromFile with decoder option

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/configuration.md

Configures the JSON decoder to use for parsing items. Built-in decoders include ExtJsonDecoder, PassThruDecoder, ErrorWrappingDecoder, and StringOnlyDecoder.

```APIDOC
## [PHP] Items::fromFile with decoder option

### Description
Configures the JSON decoder to use for parsing items. Built-in decoders include ExtJsonDecoder, PassThruDecoder, ErrorWrappingDecoder, and StringOnlyDecoder.

### Method
PHP static factory method

### Endpoint
Items::fromFile(string $filename, array $options)

### Parameters
#### Options
- **decoder** (ItemDecoder) - Optional - Must implement JsonMachine\JsonDecoder\ItemDecoder. Default is ExtJsonDecoder. ExtJsonDecoder mirrors json_decode($json, $assoc, $depth, $options). PassThruDecoder yields raw JSON strings. ErrorWrappingDecoder wraps decode failures in DecodingError values. StringOnlyDecoder is used internally in recursive mode.

### Request Example
```php
use JsonMachine\Items;
use JsonMachine\JsonDecoder\ExtJsonDecoder;
use JsonMachine\JsonDecoder\ErrorWrappingDecoder;

$items = Items::fromFile('data.json', ['decoder' => new ExtJsonDecoder(true)]);            // arrays
$items = Items::fromFile('data.json', ['decoder' => new ErrorWrappingDecoder(new ExtJsonDecoder())]);
```

### Response
Returns an Items instance for iteration.
```

--------------------------------

### Autoloading::autoloader() method signature

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/FunctionsAndAutoloading.md

Static public method that registers loading for the JsonMachine\ prefix per PSR-4 rules. Ignores classes outside the prefix.

```php
static public function autoloader(string $class)
```

--------------------------------

### getJsonPointers()

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Returns the configured JSON Pointer(s) as a list. An empty string `''` means the document main level.

```APIDOC
## getJsonPointers()

### Description
Returns the configured JSON Pointer(s) as a list. An empty string `''` means the document main level.

### Method
`getJsonPointers`

### Returns
- **Type**: `string[]`
- **Description**: The configured JSON Pointer(s) as a list.
```

--------------------------------

### getLine()

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Tokens.md

Returns the current line number. Always returns 1 because the fast lexer does not track progress.

```APIDOC
## getLine()

### Description
Returns the current line number. Always returns 1 because the fast lexer does not track progress.

### Signature
```php
public function getLine(): int
```

### Returns
`int` — Always returns `1`.
```

--------------------------------

### ExtJsonDecoder::__construct

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/JsonDecoder.md

Constructor for the ExtJsonDecoder class, mirroring json_decode's signature. It initializes the decoder with options for associative arrays, depth, and JSON options.

```APIDOC
## ExtJsonDecoder::__construct

### Description
Constructor for the ExtJsonDecoder class, mirroring json_decode's signature. It initializes the decoder with options for associative arrays, depth, and JSON options.

### Method
`__construct`

### Signature
```php
public function __construct($assoc = false, $depth = 512, $options = 0)
```

### Parameters
- `$assoc` (bool) - Optional - Default: `false` - When `true`, objects are decoded to associative arrays.
- `$depth` (int) - Optional - Default: `512` - Maximum nesting depth of decoded structures (same as `json_decode` `$depth`).
- `$options` (int) - Optional - Default: `0` - Bitmask of `json_decode` JSON_* options (e.g. `JSON_BIGINT_AS_STRING`).

### Source
`src/JsonDecoder/ExtJsonDecoder.php:29`
```

--------------------------------

### Return arrays instead of objects with ExtJsonDecoder

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Pass ExtJsonDecoder(true) as the 'decoder' option to make Items return associative arrays instead of objects for each item.

```php
<?php

use JsonMachine\JsonDecoder\ExtJsonDecoder;
use JsonMachine\Items;

$objects = Items::fromFile('path/to.json', ['decoder' => new ExtJsonDecoder(true)]);

```

--------------------------------

### Using StringOnlyDecoder with ExtJsonDecoder

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/JsonDecoder.md

Shows how to instantiate StringOnlyDecoder with an ExtJsonDecoder as the inner decoder for decoding string values.

```php
use JsonMachine\JsonDecoder\StringOnlyDecoder;
use JsonMachine\JsonDecoder\ExtJsonDecoder;

$decoder = new StringOnlyDecoder(new ExtJsonDecoder());
```

--------------------------------

### Parser::__construct

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Parser.md

Creates a new Parser instance that consumes a stream of JSON tokens and yields values matching the given JSON Pointer(s). The constructor validates the token source and JSON pointers, throwing exceptions for invalid input.

```APIDOC
## Parser::__construct

### Description
Creates a new Parser instance that consumes a stream of JSON tokens and yields values matching the given JSON Pointer(s). The constructor validates the token source and JSON pointers, throwing exceptions for invalid input.

### Method
Constructor

### Signature
```php
public function __construct(Traversable $tokens, $jsonPointer = '', ?ItemDecoder $jsonDecoder = null, $recursive = false)
```

### Parameters
- `$tokens` (Traversable) - Required - Token source; must be `Iterator` or `IteratorAggregate`.
- `$jsonPointer` (string | string[]) - Optional - JSON Pointer(s) per RFC 6901. Empty string iterates the document's main level. Validated by `ValidJsonPointers`.
- `$jsonDecoder` (?ItemDecoder) - Optional - Decoder for item keys/values. `null` falls back to `new ExtJsonDecoder()`; with `$recursive = true` the decoder is wrapped in `StringOnlyDecoder`.
- `$recursive` (bool) - Optional - When `true`, compound values are yielded as nested `Parser` instances (via `ResumableIteratorAggregateProxy`) instead of decoded arrays/objects.

### Throws
- `JsonMachine\Exception\InvalidArgumentException` - if `$tokens` is neither `Iterator` nor `IteratorAggregate` ("$tokens must be either an instance of Iterator or IteratorAggregate."), or if a JSON Pointer is malformed / pointers intersect (from `ValidJsonPointers`).

### Example
```php
use JsonMachine\Parser;
use JsonMachine\Tokens;
use JsonMachine\JsonDecoder\ExtJsonDecoder;

$parser = new Parser(
    new Tokens(['{"a":1,"b":2}']),   // chunk iterable
    '/a',
    new ExtJsonDecoder()
);
foreach ($parser as $key => $value) {
    // $key === 'a', $value === 1
}
```
```

--------------------------------

### getLine()

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/TokensWithDebugging.md

Returns the 1-based line number of the lexeme currently being processed, incremented on newline characters.

```APIDOC
## getLine()

### Description
Returns the current line number (1-based) of the token being processed.

### Returns
- **int** - 1-based line number.

### Example
```php
$line = $tokens->getLine();
```
```

--------------------------------

### fromStream method signature

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Declares the static factory that consumes chunks from a PHP stream resource. Accepts the same $options array and throws InvalidArgumentException on invalid options or pointer values.

```php
public static function fromStream($stream, array $options = []): self
```

--------------------------------

### getMatchedJsonPointer()

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Parser.md

Returns the configured pointer that matched the current position, with wildcard `-` segments intact (e.g. `/results/-/color`). The pointer is re-evaluated on each path change by `getMatchingJsonPointerPath()`, which picks the deepest applicable pointer when several are configured. Throws an exception if called outside iteration.

```APIDOC
## getMatchedJsonPointer()

### Description
Returns the configured pointer that matched the current position, with wildcard `-` segments intact (e.g. `/results/-/color`). The pointer is re-evaluated on each path change by `getMatchingJsonPointerPath()`, which picks the deepest applicable pointer when several are configured. Throws an exception if called outside iteration.

### Method
`getMatchedJsonPointer`

### Signature
```php
public function getMatchedJsonPointer(): string
```

### Returns
- `string` — the configured pointer that matched the current position (wildcard `-` segments intact, e.g. `/results/-/color`).

### Throws
- `JsonMachine\Exception\JsonMachineException` — outside iteration (`src/Parser.php:425`).
```

--------------------------------

### getMatchedJsonPointer()

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Returns the configured pointer that matched the currently yielded item, including `-` wildcard segments unchanged (e.g., `/results/-/color`). Throws an exception when called outside a loop.

```APIDOC
## getMatchedJsonPointer()

### Description
Returns the configured pointer that matched the currently yielded item (includes `-` wildcard segments unchanged), e.g. `/results/-/color`. Throws `JsonMachine\Exception\JsonMachineException` when called outside a loop.

### Method
`getMatchedJsonPointer`

### Returns
- **Type**: `string`
- **Description**: The configured pointer that matched the currently yielded item.

### Throws
- **`JsonMachine\Exception\JsonMachineException`** - When called outside a loop.

### Usage Example
```php
$fruits = Items::fromFile('fruitsArray.json', ['pointer' => '/results/-/color']);

foreach ($fruits as $key => $value) {
    if ($fruits->getMatchedJsonPointer() === '/results/-/color') {
        $actual = $fruits->getCurrentJsonPointer(); // '/results/0/color', '/results/1/color', ...
    }
}
```
```

--------------------------------

### ExtJsonDecoder::instance

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/JsonDecoder.md

Static method that returns a process-wide shared ExtJsonDecoder instance, lazily created as a singleton. It uses default constructor arguments only.

```APIDOC
## ExtJsonDecoder::instance

### Description
Static method that returns a process-wide shared ExtJsonDecoder instance, lazily created as a singleton. It uses default constructor arguments only.

### Method
`instance` (static)

### Signature
```php
public static function instance(): self
```

### Returns
- `self` - A shared `ExtJsonDecoder` instance.

### Source
`src/JsonDecoder/ExtJsonDecoder.php:52`
```

--------------------------------

### ItemsOptions::defaultOptions() - Default Configuration Values

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/configuration.md

Returns the default options array used by JSON Machine when no custom options are provided. The defaults are: pointer set to an empty string, decoder set to a new ExtJsonDecoder instance, and debug set to false. This method is defined in src/ItemsOptions.php at lines 77-84.

```php
public static function defaultOptions(): array
{
    return [
        'pointer' => '',
        'decoder' => new ExtJsonDecoder(),
        'debug' => false,
    ];
}
```

--------------------------------

### ItemsOptions::__construct

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/ItemsOptions.md

Creates an ItemsOptions instance that validates and normalizes the options array for Items and RecursiveItems factories. Throws InvalidArgumentException for unknown option names or type errors.

```APIDOC
## ItemsOptions::__construct

### Description
Creates an ItemsOptions instance that validates and normalizes the options array for Items and RecursiveItems factories. Throws InvalidArgumentException for unknown option names or type errors.

### Method
Constructor

### Signature
```php
public function __construct(array $options = [])
```

### Parameters
- `$options` (array) - Optional - Key/value map of option names to values. Unknown names and type errors raise exceptions.

### Throws
- `JsonMachine\Exception\InvalidArgumentException` - Unknown option name or wrong value type.

### Example
```php
use JsonMachine\ItemsOptions;

$options = new ItemsOptions(['pointer' => '/results', 'debug' => true]);
$options['decoder'];       // ExtJsonDecoder instance (default)
$options->toArray();        // validated option map
```
```

--------------------------------

### advanceToKey method signature

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/RecursiveItems.md

Declares the advanceToKey method that moves the internal cursor to the given key and returns the value at that key. Throws OutOfBoundsException if the key is not found.

```php
public function advanceToKey($key)
```

--------------------------------

### Parse a JSON document with Items::fromFile

Source: https://github.com/halaxa/json-machine/blob/master/README.md

Iterates over top-level key-value pairs of a JSON object. The foreach key is the property name and the value is a decoded object. Use this for large documents to keep memory usage constant.

```json
// fruits.json
{
    "apple": {
        "color": "red"
    },
    "pear": {
        "color": "yellow"
    }
}

```

```php
<?php

use \JsonMachine\Items;

$fruits = Items::fromFile('fruits.json');

foreach ($fruits as $name => $data) {
    // 1st iteration: $name === "apple" and $data->color === "red"
    // 2nd iteration: $name === "pear" and $data->color === "yellow"
}

```

--------------------------------

### fromString method signature

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/Items.md

Declares the static factory that parses an in-memory JSON string. Accepts the same $options array as other factories and throws InvalidArgumentException on invalid options or pointer values.

```php
public static function fromString($string, array $options = []): self
```

--------------------------------

### Skip malformed items with ErrorWrappingDecoder

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/errors.md

Uses ErrorWrappingDecoder with ExtJsonDecoder to skip malformed items without throwing. Note: only covers item-level decode failures; structural SyntaxErrorExceptions between items still throw.

```php
use JsonMachine\Items;
use JsonMachine\JsonDecoder\DecodingError;
use JsonMachine\JsonDecoder\ErrorWrappingDecoder;
use JsonMachine\JsonDecoder\ExtJsonDecoder;

$items = Items::fromFile('dirty.json', [
    'decoder' => new ErrorWrappingDecoder(new ExtJsonDecoder()),
]);
foreach ($items as $key => $item) {
    if ($key instanceof DecodingError || $item instanceof DecodingError) {
        continue; // skip this malformed item, keep parsing
    }
}
```

--------------------------------

### getColumn method signature

Source: https://github.com/halaxa/json-machine/blob/master/_autodocs/api-reference/TokensWithDebugging.md

Returns the 1-based column offset of the current lexeme within its line.

```php
public function getColumn()
```
Tokens:
Raw