johnstevenson/json-works

Create, edit, query and validate json

Installs: 522

Dependents: 0

Stars: 9

Watchers: 1

Forks: 1

Open Issues: 2

Language: PHP

v1.0.1 2013-04-25 19:47 UTC

README

Build Status

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

Contents

About

The library is intended to be used with nested json structures, or with json data that needs validation. Or in any situation where you would find it is easier to do something like this:

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

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

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

which will give you the following json:

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

You can query this value by calling:

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

and update it with:

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

and move it with:

$document->moveValue('/path/to/nested/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. This allows you to validate your data. The following example schema describes an array containing objects whose properties are all required and whose types are defined.

{
    "items": {
        "properties": {
            "firstName": {"type": "string"},
            "lastName": {"type": "string"}                  
        },
        "required": ["firstName", "lastName"]
    }
}

Now when you try to add values, Json-Works will only do so if they are valid. So you have to check.

$document->loadSchema($schema);

$result = $document->addValue('/-', array('firstName'=> 'Fred', 'lastName' => 'Bloggs'));
# true

$result = $document->addValue('/-', array('firstName'=> 'Fred', 'lastName' => 3));
# false, lastName is not a string

$result = $document->addValue('/0', array('firstName'=> 'Fred'));
# true, required values are not checked when we are building

# but are checked if we validate directly

$result = $document->validate();
# false - required lastName is missing

Without a schema, any value can be added anywhere.

Installation

The easiest way is through composer. Just create a composer.json file and run php composer.phar install to install it:

{
    "require": {
        "johnstevenson/json-works": "1.0.*"
    }
}

Then include require 'vendor/autoload.php' somewhere in your bootstrap code. Alternatively, you can download and extract it then point a PSR-0 autoloader to the src directory.

Usage

Full usage documentation is available in the Wiki.

License

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