Download the PHP package celestriode/json-utils without Composer

celestriode/json-utils

Provides a handful of utilities for simple interfacing with a JSON-derived object.

1. General utilities
   1. Deserializing
   2. The Json object
   3. Json datatypes
   4. The JsonCollection object
   5. Normalizing
2. Predicates
   1. Packaged predicates
3. Structural validation
   1. Defining a structure
   2. Reports
   3. The Report object
   4. Statistical reports
   5. Audits
   6. Adding an audit to a structure

General utilities

Many utilities in this library require the use of a Celestriode\JsonUtils\Json object, which can be created manually or obtained by deserializing a JSON-formatted string.

Deserializing

If you do not already have a Json object, start by deserializing a JSON-formatted string.

This uses the seldaek/jsonlint library for linting and will not catch errors thrown by it; that's up to you to handle.

The Json object

After deserializing, the Celestriode\JsonUtils\Json object is returned. This has a number of interfacing methods to more easily access data of the JSON field.

Objects

The following are methods specific to JSON objects. If !$json->isType(Json::OBJECT), almost all of these methods will throw a Celestriode\JsonUtils\Exception\WrongType exception. The one outlier is hasField(), which will simply return false instead of throwing.

Arrays

The following are methods specific to JSON arrays. If !$json->isType(Json::ARRAY), all of these methods will throw a Celestriode\JsonUtils\Exception\WrongType exception.

Setters

If creating a Json object manually, or you would like to manipulate the returned object, there are also a number of setters.

Json datatypes

The following is a list of constants provided via the Celestriode\JsonUtils\Json class to correspond to each datatype that can be present in JSON.

These would primarily be used when checking the datatype of a Json object.

The JsonCollection object

The Celestriode\JsonUtils\JsonCollection object, which extends Celestriode\JsonUtils\Json, is primarily used as a result of $json->getFields() and $json->getElements(). It holds a list of Celestriode\JsonUtils\Json objects.

It will also override some methods from Json:

Normalizing

These methods transform an integer into a datatype string, and a datatype string into an integer. The integer values correspond to the constants provided by the Json datatypes, while the string values correspond to PHP's gettype() return values.

Predicates

Various features, such as $json->checkJson(), make use of predicates to perform a test. All predicates must implement Celestriode\JsonUtils\IPredicate, which comes with two required methods: a test to check the Report object with a preset report (where applicable).

A standard predicate Celestriode\JsonUtils\Predicates\Predicate is available to avoid having to supply the report every time, since the test is typically more important. Simply extend that predicate and add the test.

Packaged predicates

There are also a number of predicates that come with the library available to use. These are all in the Celestriode\JsonUtils\Predicates namespace.

For example, the following runs a test against a Json object to ensure that it, as a scalar value, matches any of the listed values.

Singleton predicates

Anything extending Celestriode\JsonUtils\Predicates\Predicate (such as all of the packaged predicates) or making use of the Celestriode\JsonUtils\TMultiSingleton trait will have access to the instance() static method. This will create a singleton of the predicate to reduce memory load from having unnecessary duplicate objects in memory.

This should not be used if the predicate needs to store volatile data to, for example, use in the test() or getReport() methods. In those cases, always create a new class. A general rule of thumb is if you're using __construct() in a custom predicate, you should not be using instance().

In the case of packaged predicates, AlwaysTrue and AlwaysFalse should always use instance(). The other predicates should not.

Structural validation

You can compare a reports on the structure itself. This is done using the Celestriode\JsonUtils\Structure class, which comes with many helper methods to simplify structure definitions.

Defining a structure

The following are a list of methods available to aid in building a structure. They define the expected key names and datatypes within a JSON structure.

Primitive values

These methods primarily define primitive values as seen in JSON.

For example, the following specifies a structure that has a root object. Within it is an optional string field with the key "hello", and a required numeric field with the key "goodbye".

Object values

The Structure::object(string $key = null, bool $required = true, Structure ...$children): Structure method defines an object with optional $key, $required flag, and $children of the object to continue comparison with fields nested inside.

Array values

The Structure::array(string $key = null, bool $required = true, Structure ...$elements): Structure method defines an array with optional $key, $required flag, and a variety of valid $elements within the array. Its direct children essentially define the datatypes of the elements, and are therefore keyless. You can define multiple child elements to accept a variety of different datatypes within the array.

Mixed values

The Structure::mixed(string $key = null, int $type = Json::ANY, bool $required = true, Structure ...$children): Structure method allows you to specify any datatype combo you want. An optional $key, $required flag, and $children can be supplied. The children will be used as either child fields if the datatype is an object, or as child elements if the datatype is an array.

For example, the following specifies a mixed structure within an array that can be a string, boolean, or an object with the specified children.

Placeholder values

The Structure::placeholder(int $type, Structure ...$children): Structure method defines a value where the key can be anything, as long as it matches the expected $type. Any fields that do not match the type can still be validated by other defined structures at the same depth. $children are added as either child fields or elements depending on if $type is an object or array.

Branching values

The Structure::branch(string $label, IPredicate $predicate, Structure ...$branches): Structure method defines a structure that will introduce new $structures to the tree provided that the $predicate succeeds. The $label is simply a friendly name to give the branch itself, which can be used in reports.

Ascending values

The Structure::ascend(UuidInterface $ancestor, string $key = null, bool $required = true): Structure method makes use of an ancestor's structure to validate the JSON at this depth. This can be used for recursive structures. The ancestor to locate is defined using Ramsey\Uuid\UuidInterface, and the ancestor itself must have the specified UUID by using the setUuid() method on the ancestral structure.

If no valid ancestor was found, Celestriode\JsonUtils\Exception\BadStructure is thrown.

Reports

Once you have defined a structure, you can run the compare(Json $json, Reports $reports = null): Reports method. This will take in the deserialized JSON, and can optionally take in a prebuilt Celestriode\JsonUtils\Structure\Reports object. It will populate the reports and return the same object. If no reports are provided, it will create a new one.

The tree structure of reports will match the tree structure defined with Celestriode\JsonUtils\Structure. Each level of reports will contain the relevant Celestriode\JsonUtils\Json object for that depth, along with any reports of various levels.

The individual reports themselves make use of the Celestriode\JsonUtils\Structure\Report class.

To simply check if the structure was valid, you can run the hasAnyErrors() method from the reports. If true, it failed in some manner.

Reports methods

The following are various methods available with reports.

The Report object

Creating a report can be done with 3 primary helper methods, which define the severity of the report:

The format makes use of PHP's sprintf() function, allowing you to more easily fill in data. The standard Report class comes with two methods to sanitize input, since reports are primarily going to be displayed to the user. These methods are Report::key(string ...$keys): string and Report::value(...$values): string. These methods should especially be used on JSON data that you plan to display, as htmlentities() is used to prevent embedding HTML.

Statistical reports

Alongside the primary Reports class is the Celestriode\JsonUtils\Structure\StatisticalReports class. This class will automatically populate Celestriode\JsonUtils\Structure\Statistics using the incoming JSON structure. If you would prefer to use this, you can pass it into the compare() method when validating a structure.

Use the getStatistics(): Statistics method to get the relevant Statistics object. With that object, use the method getStatistics(): array, which will return an array structure with generated statistics of the JSON data.

Audits

When validating a JSON structure, sometimes it's necessary to get more specific than simply checking if fields exist. Audits allow you to get much more personal with the incoming structure. In particular, audits should be used to add reports, which differs from predicates which should not directly add reports.

An audit is defined by the Celestriode\JsonUtils\IAudit interface, where the audit() method takes in the structure, Json, and reports all at the current depth of the JSON tree. However, like predicates, there is a standard audit available at Celestriode\JsonUtils\Structure\Audits\Audit. It also makes use of the Celestriode\JsonUtils\TMultiSingleton trait, giving you access to instance() when necessary.

You can simple extend that audit class to gain access to that feature while specifying the audit() method yourself. For example, the following adds an error if the value of the audit wasn't the correct, hard-coded value.

Packaged audits

There are also a number of audits that come with the library available to use. These are all in the Celestriode\JsonUtils\Structure\Audits namespace.

Adding an audit to a structure

Simply use the addAudit(IAudit $audit, IPredicate ...$predicates): Structure method on a structure to set an audit. You can optionally specify $predicates, which must all pass before running the audit. This can be useful to prevent adding reports unless a certain criteria is met beforehand.

Final example

The following complex structure can successfully match against Minecraft's text component, though some validation (such as NBT parsing) is missing.