americanreading/refresolver

Resolves references to extenral files in objects

RefResolver

Use RefResolver to resolve references or "flatten" objects., _(*1)

RefResolver works with any object, but is mostly likely to be useful for working with JSON, particularly JSON Schema documents and Swagger configuration files., _(*2)

References

The format of the references follows the syntax used by JSON Schema. However, there is no restriction on where the reference exists inside the structure., _(*3)

To create a reference, include a $ref property on an object that points to the path for a file describing an object. The path may be a local file path or an HTTP URI., _(*4)

Example

Given this file at http://www.myjsonfile/cats.json, _(*5)

{
    "cats": [
        {
            "name": "Molly",
            "color": "Calico"
        },
        {
            "name": "Oscar",
            "color": "Orange"
        }
    ]
}

We can include a reference to this file inside another JSON structure., _(*6)

<?php
$json = <<<JSON
{
    "dog": "Bear",
    "\$ref": "http://www.myjsonfile/cats.json"
}
JSON

$obj = json_decode($json);

$resolver new RefResolver();
$resolver->resolve($obj);

After calling $resolver->resolve($obj), $obj will contain a "flattened" structure with the contents of the http://www.myjsonfile/cats.json converted to an object and augmented onto $obj., _(*7)

$obj will now look like this (shown as prettyprinted JSON):, _(*8)

{
    "dog": "Bear",
    "cats": [
        {
            "name": "Molly",
            "color": "Calico"
        },
        {
            "name": "Oscar",
            "color": "Orange"
        }
    ]
}

Custom resolver function

By default, the RefResolver instance will take the value of a $ref property, pass it to file_get_contents, then pass that result to json_decode, and augment the decoded object., _(*9)

You may customize this behavior by passing a callable to the constructor. The callable must expect the value of the $ref property as an argument and return an object or null., _(*10)

To parse the contents of the reference as XML instead of JSON, you could use a custom function like this:, _(*11)

<?php
$resolverFn = function ($ref) {
    $contents = @file_get_contents($ref);
    if ($contents) {
        return simplexml_load_string($contents);
    }
    return null;
};

Caveats

There is no safeguard in place to check against circular references., _(*12)