/**
* Frame a JSON-LD document according a supplied frame
*
* Both the document and the frame can be supplied directly as string,
* by passing a file path, or by passing a URL.
*
* Usage:
*
* $result = JsonLD::frame('document.jsonld', 'frame.jsonldf');
* print_r($compacted);
*
* It is possible to configure the framing process by setting the options
* parameter accordingly. Available options are:
*
* <dl>
* <dt>base</dt>
* <dd>The base IRI of the input document.</dd>
*
* <dt>expandContext</dt>
* <dd>An optional context to use additionally to the context embedded
* in input when expanding the input.</dd>
*
* <dt>optimize</dt>
* <dd>If set to true, the processor is free to optimize the result to
* produce an even compacter representation than the algorithm
* described by the official JSON-LD specification.</dd>
*
* <dt>compactArrays</dt>
* <dd>If set to true, arrays holding just one element are compacted
* to scalars, otherwise the arrays are kept as arrays.</dd>
* </dl>
*
* The options parameter might be passed as associative array or as
* object.
*
* @param string|object|array $input The JSON-LD document to compact.
* @param string|object $frame The frame.
* @param null|array|object $options Options to configure the framing
* process.
*
* @return mixed The framed JSON-LD document.
*
* @throws JsonLdException
*
* @api
*/
public static function frame($input, $frame, $options = null)
{
$options = self::mergeOptions($options);
$input = self::expand($input, $options);
$frame = Processor::loadDocument($frame);
if (false === is_object($frame)) {
throw new JsonLdException(JsonLdException::UNSPECIFIED, 'Invalid frame detected. It must be an object.', $frame);
}
$processor = new Processor($options);
// Store the frame as $frame gets modified
$frameContext = new Object();
if (property_exists($frame, '@context')) {
$frameContext->{'@context'} = $frame->{'@context'};
}
// Expand the frame
$processor->expand($frame, array(), null, true);
// and optimize away default graph (@graph as the only property at the top-level object)
if (is_object($frame) && property_exists($frame, '@graph') && 1 === count(get_object_vars($frame))) {
$frame = $frame->{'@graph'};
}
if (false === is_array($frame)) {
$frame = array($frame);
}
// Frame the input document
$result = $processor->frame($input, $frame);
// Compact the result using the frame's active context
return self::doCompact($result, $frameContext, $options, true);
}
