byjg / anydataset-json

6.0.0 2025-11-24 18:02 UTC

Requires

• php: >=8.3 <8.6
• ext-json: *
• byjg/anydataset: ^6.0

Requires (Dev)

• phpunit/phpunit: ^10.5|^11.5
• vimeo/psalm: ^5.9|^6.13

Suggests

• ext-curl: *

Provides

• byjg/anydataset-implementation: 1.0

MIT

Published on Packagist.org on 2025-11-26 03:14 UTC

README

sidebar_key	anydataset-json
sidebar_category	data-access
tags	php anydataset

JSON Dataset Abstraction

Read a JSON document as a table: point at a path, declare the fields, iterate the rows.

See more about Anydataset here.

Why

json_decode() gives you nested arrays, and every consumer then writes its own loops, isset() checks and casts to reach the data. When the JSON comes from an API, the shape you depend on is scattered across that code.

JsonDataset declares it in one place. Point at the list with a path, declare each field with its path, type and whether it is required, and read rows:

$iterator = (new JsonDataset($json))
    ->getIterator('/menu/items')
    ->withFields([
        JsonFieldDefinition::create('name', 'id'),
        JsonFieldDefinition::create('version', 'metadata/version')->required()->ofTypeString(),
    ]);

The result is the same iterator of rows as every other AnyDataset source, so the code that reads it does not care that the data was JSON.

Concept

The AnyDataset-Json is an abstraction layer to read a JSON data and transform it into a dataset, and you can manipulate it as a table.

Some features:

• Read a JSON file or string
• Navigate through nested JSON structures using path notation
• Define and extract fields with validation
• Create dynamic fields using closures
• Validate data types (string, int, float, bool)
• Handle required fields and default values

Basic Example

example.json:

{
   "menu":{
      "header":"SVG Viewer",
      "items":[
         {
            "id":"Open",
            "metadata":{
               "version":"1",
               "date":"NA"
            }
         },
         {
            "id":"OpenNew",
            "label":"Open New",
            "metadata":{
               "version":"2",
               "date":"2021-10-01"
            }
         }
      ]
   }
}

example.php:

$json = file_get_contents('example.json');

$dataset = new \ByJG\AnyDataset\Json\JsonDataset($json);

// Basic usage with field definitions
$iterator = $dataset->getIterator("/menu/items")
                        ->withFields([
                            \ByJG\AnyDataset\Json\JsonFieldDefinition::create("name", "id"),
                            \ByJG\AnyDataset\Json\JsonFieldDefinition::create("version", "metadata/version")
                                ->required()
                                ->ofTypeString()
                        ]);

foreach ($iterator as $row) {
    echo $row->get('name');       // Print "Open", "OpenNew"
    echo $row->get('version');    // Print "1", "2"
}

Features

• Simple Manipulation
• Creating dynamic fields
• The JsonFieldDefinition

Installation

composer require "byjg/anydataset-json"

Running Tests

vendor/bin/phpunit

Open source ByJG