johnstevenson/json-works

Create, edit, query and validate json

2.1.0 2023-04-17 13:36 UTC

Requires

• php: ^7.4 || ^8.0
• composer/pcre: ^3.1

Requires (Dev)

• phpstan/phpstan: ^1.0
• phpstan/phpstan-strict-rules: ^1.1
• phpunit/phpunit: ^9.6.5

MIT

• John Stevenson

• json
• schema
• validator
• builder

README

A PHP library to create, edit, query and validate JSON.

Installation

Install the latest version with:

$ composer require johnstevenson/json-works

Requirements

• PHP 7.4 minimum, although using the latest PHP version is highly recommended.

Usage

The library is intended to be used with complex json structures, or with json data that needs validation. Full usage information is available in the documentation.

• Overview
• Validation

Overview

Json-Works allows you to create, edit and query json data using JSON Pointer syntax. For example:

<?php
$document = new JohnStevenson\JsonWorks\Document();

$document->addValue('/path/to/array/-', ['firstName'=> 'Fred', 'lastName' => 'Blogg']);

// prettyPrint
$json = $document->toJson(true);

which will give you the following json:

{
    "path": {
        "to": {
            "array": [
                {
                  "firstName": "Fred",
                  "lastName": "Blogg"
                }
            ]
        }
    }
}

You can query this value by calling:

$person = $document->getValue('/path/to/array/0');

and update it with:

$document->addValue('/path/to/array/0/lastName', 'Bloggs');

and move it with:

$document->moveValue('/path/to/array/0', '/users/-');

$document->tidy();
$json = $document->toJson(true);

to end up with:

{
    "users": [
        {
            "firstName": "Fred",
            "lastName": "Bloggs"
        }
    ]
}

then delete it with:

$document->deleteValue('/users/0');

Validation

Json-Works includes an implementation of JSON Schema, version 4, which allows you to validate json data. If the document contains invalid or missing value data, the validation will fail with the error in $document->getError().

$document = new JohnStevenson\JsonWorks\Document();

$document->loadData('path/to/data.json');
$document->loadScheme('path/to/schema.json');

if (!$document->validate()) {
    $error = $document->getError();
}

You can also validate data whilst building a document. The following example schema describes an array containing objects whose properties are all required and whose types are defined.

// schemas can be very simple
{
    "items": {
        "properties": {
            "firstName": { "type": "string" },
            "lastName": { "type": "string" }
        },
        "required": [ "firstName", "lastName" ]
    }
}

Now you can check if your data is valid:

$document->loadSchema($schema);
$document->addValue('/-', ['firstName'=> 'Fred']);

if (!$document->validate()) {
    $error = $document->getError();
    # "Property: '/0'. Error: is missing required property 'lastName'"
}

Without a schema, any value can be added anywhere.

License

Json-Works is licensed under the MIT License - see the LICENSE file for details.