You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
php-json-ld/jsonld.php

5586 lines
173 KiB

<?php
/**
* PHP implementation of the JSON-LD API.
* Version: 0.1.0
*
* @author Dave Longley
*
* BSD 3-Clause License
10 years ago
* Copyright (c) 2011-2013 Digital Bazaar, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* Neither the name of the Digital Bazaar, Inc. nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
* IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
* TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
* TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* Performs JSON-LD compaction.
*
* @param mixed $input the JSON-LD object to compact.
* @param mixed $ctx the context to compact with.
* @param assoc [$options] options to use:
* [base] the base IRI to use.
* [graph] true to always output a top-level graph (default: false).
* [documentLoader(url)] the document loader.
*
* @return mixed the compacted JSON-LD output.
*/
function jsonld_compact($input, $ctx, $options=array()) {
$p = new JsonLdProcessor();
return $p->compact($input, $ctx, $options);
}
/**
* Performs JSON-LD expansion.
*
* @param mixed $input the JSON-LD object to expand.
* @param assoc[$options] the options to use:
* [base] the base IRI to use.
* [documentLoader(url)] the document loader.
*
* @return array the expanded JSON-LD output.
*/
function jsonld_expand($input, $options=array()) {
$p = new JsonLdProcessor();
return $p->expand($input, $options);
}
10 years ago
/**
* Performs JSON-LD flattening.
*
* @param mixed $input the JSON-LD to flatten.
* @param mixed $ctx the context to use to compact the flattened output, or
10 years ago
* null.
* @param [options] the options to use:
* [base] the base IRI to use.
* [documentLoader(url)] the document loader.
*
10 years ago
* @return mixed the flattened JSON-LD output.
*/
function jsonld_flatten($input, $ctx, $options=array()) {
10 years ago
$p = new JsonLdProcessor();
return $p->flatten($input, $ctx, $options);
}
/**
* Performs JSON-LD framing.
*
* @param mixed $input the JSON-LD object to frame.
* @param stdClass $frame the JSON-LD frame to use.
* @param assoc [$options] the framing options.
* [base] the base IRI to use.
* [embed] default @embed flag (default: true).
* [explicit] default @explicit flag (default: false).
* [omitDefault] default @omitDefault flag (default: false).
* [documentLoader(url)] the document loader.
*
* @return stdClass the framed JSON-LD output.
*/
function jsonld_frame($input, $frame, $options=array()) {
$p = new JsonLdProcessor();
return $p->frame($input, $frame, $options);
}
/**
* Performs RDF dataset normalization on the given JSON-LD input. The output
* is an RDF dataset unless the 'format' option is used.
*
* @param mixed $input the JSON-LD object to normalize.
* @param assoc [$options] the options to use:
* [base] the base IRI to use.
* [format] the format if output is a string:
* 'application/nquads' for N-Quads.
* [documentLoader(url)] the document loader.
*
* @return mixed the normalized output.
*/
function jsonld_normalize($input, $options=array()) {
$p = new JsonLdProcessor();
return $p->normalize($input, $options);
}
/**
* Converts an RDF dataset to JSON-LD.
*
* @param mixed $input a serialized string of RDF in a format specified
* by the format option or an RDF dataset to convert.
11 years ago
* @param assoc [$options] the options to use:
* [format] the format if input not an array:
* 'application/nquads' for N-Quads (default).
* [useRdfType] true to use rdf:type, false to use @type
* (default: false).
* [useNativeTypes] true to convert XSD types into native types
* (boolean, integer, double), false not to (default: false).
*
* @return array the JSON-LD output.
*/
function jsonld_from_rdf($input, $options=array()) {
$p = new JsonLdProcessor();
return $p->fromRDF($input, $options);
}
/**
* Outputs the RDF dataset found in the given JSON-LD object.
*
* @param mixed $input the JSON-LD object.
* @param assoc [$options] the options to use:
11 years ago
* [base] the base IRI to use.
* [format] the format to use to output a string:
* 'application/nquads' for N-Quads.
* [produceGeneralizedRdf] true to output generalized RDF, false
* to produce only standard RDF (default: false).
* [documentLoader(url)] the document loader.
*
* @return mixed the resulting RDF dataset (or a serialization of it).
*/
function jsonld_to_rdf($input, $options=array()) {
$p = new JsonLdProcessor();
return $p->toRDF($input, $options);
}
/**
* Relabels all blank nodes in the given JSON-LD input.
*
* @param mixed input the JSON-LD input.
*/
function jsonld_relabel_blank_nodes($input) {
$p = new JsonLdProcessor();
return $p->_labelBlankNodes(new UniqueNamer('_:b'), $input);
}
/** JSON-LD shared in-memory cache. */
global $jsonld_cache;
$jsonld_cache = new stdClass();
/** The default active context cache. */
$jsonld_cache->activeCtx = new ActiveContextCache();
/** Stores the default JSON-LD document loader. */
global $jsonld_default_load_document;
$jsonld_default_load_document = null;
/**
* Sets the default JSON-LD document loader.
*
* @param callable load_document(url) the document loader.
*/
function jsonld_set_document_loader($load_document) {
global $jsonld_default_load_document;
$jsonld_default_load_document = $load_document;
}
/**
* Retrieves JSON-LD at the given URL.
*
10 years ago
* @param string $url the URL to retrieve.
*
* @return the JSON-LD.
*/
function jsonld_get_url($url) {
global $jsonld_default_load_document;
if($jsonld_default_load_document !== null) {
$document_loader = $jsonld_default_load_document;
}
else {
$document_loader = $jsonld_default_document_loader;
}
$remote_doc = $document_loader($url);
if($remote_doc) {
return $remote_doc->document;
}
return null;
}
10 years ago
/**
* The default implementation to retrieve JSON-LD at the given URL.
*
* @param string $url the URL to to retrieve.
*
* @return stdClass the RemoteDocument object.
10 years ago
*/
function jsonld_default_document_loader($url) {
$redirects = array();
$opts = array(
'http' => array(
'method' => 'GET',
10 years ago
'header' =>
"Accept: application/ld+json\r\n" .
"User-Agent: JSON-LD PHP Client/1.0\r\n"),
'https' => array(
'verify_peer' => true,
'method' => 'GET',
'header' =>
"Accept: application/ld+json\r\n" .
"User-Agent: JSON-LD PHP Client/1.0\r\n"));
10 years ago
$stream = stream_context_create($opts);
stream_context_set_params($stream, array('notification' =>
function($notification_code, $severity, $message) use (&$redirects) {
switch($notification_code) {
case STREAM_NOTIFY_REDIRECTED:
$redirects[] = $message;
break;
};
}));
10 years ago
$result = @file_get_contents($url, false, $stream);
if($result === false) {
throw new Exception("Could not GET url: '$url'");
}
$redirs = count($redirects);
if($redirs > 0) {
$url = $redirects[$redirs - 1];
}
// return RemoteDocument
return (object)array(
'contextUrl' => null,
'document' => $result,
'documentUrl' => $url);
10 years ago
}
/**
* The default implementation to retrieve JSON-LD at the given secure URL.
*
* @param string $url the secure URL to to retrieve.
*
* @return stdClass the RemoteDocument object.
*/
function jsonld_default_secure_document_loader($url) {
if(strpos($url, 'https') !== 0) {
throw new Exception("Could not GET url: '$url'; 'https' is required.");
}
$redirects = array();
// default JSON-LD https GET implementation
$opts = array(
'https' => array(
'verify_peer' => true,
'method' => "GET",
'header' =>
"Accept: application/ld+json\r\n" .
"User-Agent: JSON-LD PHP Client/1.0\r\n"));
$stream = stream_context_create($opts);
stream_context_set_params($stream, array('notification' =>
function($notification_code, $severity, $message) use (&$redirects) {
switch($notification_code) {
case STREAM_NOTIFY_REDIRECTED:
$redirects[] = $message;
break;
};
}));
$result = @file_get_contents($url, false, $stream);
if($result === false) {
throw new Exception("Could not GET url: '$url'");
}
foreach($redirects as $redirect) {
if(strpos($redirect, 'https') !== 0) {
throw new Exception(
"Could not GET redirected url: '$redirect'; 'https' is required.");
}
$url = $redirect;
}
// return RemoteDocument
return (object)array(
'contextUrl' => null,
'document' => $result,
'documentUrl' => $url);
}
/** Registered global RDF dataset parsers hashed by content-type. */
10 years ago
global $jsonld_rdf_parsers;
$jsonld_rdf_parsers = new stdClass();
/**
* Registers a global RDF dataset parser by content-type, for use with
* jsonld_from_rdf. Global parsers will be used by JsonLdProcessors that do
10 years ago
* not register their own parsers.
*
* @param string $content_type the content-type for the parser.
* @param callable $parser(input) the parser function (takes a string as
* a parameter and returns an RDF dataset).
10 years ago
*/
function jsonld_register_rdf_parser($content_type, $parser) {
10 years ago
global $jsonld_rdf_parsers;
$jsonld_rdf_parsers->{$content_type} = $parser;
}
/**
* Unregisters a global RDF dataset parser by content-type.
10 years ago
*
* @param string $content_type the content-type for the parser.
*/
function jsonld_unregister_rdf_parser($content_type) {
global $jsonld_rdf_parsers;
10 years ago
if(property_exists($jsonld_rdf_parsers, $content_type)) {
unset($jsonld_rdf_parsers->{$content_type});
10 years ago
}
}
10 years ago
/**
* Parses a URL into its component parts.
*
* @param string $url the URL to parse.
*
* @return assoc the parsed URL.
*/
function jsonld_parse_url($url) {
if($url === null) {
$url = '';
}
$rval = parse_url($url);
// malformed url
if($rval === false) {
$rval = array();
}
$rval['href'] = $url;
if(!isset($rval['scheme'])) {
$rval['scheme'] = '';
$rval['protocol'] = '';
}
else {
$rval['protocol'] = $rval['scheme'] . ':';
}
if(!isset($rval['host'])) {
$rval['host'] = '';
}
if(!isset($rval['path'])) {
$rval['path'] = '';
}
if(isset($rval['user']) || isset($rval['pass'])) {
$rval['auth'] = '';
if(isset($rval['user'])) {
$rval['auth'] = $rval['user'];
}
if(isset($rval['pass'])) {
$rval['auth'] .= ":{$rval['pass']}";
}
}
// parse authority for unparsed relative network-path reference
if(strpos($rval['href'], ':') === false &&
strpos($rval['href'], '//') === 0 && $rval['host'] === '') {
// must parse authority from pathname
$rval['path'] = substr($rval['path'], 2);
$idx = strpos($rval['path'], '/');
if($idx === false) {
$rval['authority'] = $rval['path'];
$rval['path'] = '';
}
else {
$rval['authority'] = substr($rval['path'], 0, $idx);
$rval['path'] = substr($rval['path'], $idx);
}
}
else {
$rval['authority'] = $rval['host'];
if(isset($rval['port'])) {
$rval['authority'] .= ":{$rval['port']}";
}
if(isset($rval['auth'])) {
$rval['authority'] = "{$rval['auth']}@{$rval['authority']}";
}
}
$rval['normalizedPath'] = jsonld_remove_dot_segments(
$rval['path'], $rval['authority'] !== '');
return $rval;
}
/**
* Removes dot segments from a URL path.
*
* @param string $path the path to remove dot segments from.
* @param bool $has_authority true if the URL has an authority, false if not.
*/
function jsonld_remove_dot_segments($path, $has_authority) {
$rval = '';
if(strpos($path, '/') === 0) {
$rval = '/';
}
// RFC 3986 5.2.4 (reworked)
$input = explode('/', $path);
$output = array();
while(count($input) > 0) {
if($input[0] === '.' || ($input[0] === '' && count($input) > 1)) {
array_shift($input);
continue;
}
if($input[0] === '..') {
array_shift($input);
if($has_authority ||
(count($output) > 0 && $output[count($output) - 1] !== '..')) {
array_pop($output);
}
// leading relative URL '..'
else {
$output[] = '..';
}
continue;
}
$output[] = array_shift($input);
}
return $rval . implode('/', $output);
}
/**
* Prepends a base IRI to the given relative IRI.
*
* @param mixed $base a string or the parsed base IRI.
* @param string $iri the relative IRI.
*
* @return string the absolute IRI.
*/
function jsonld_prepend_base($base, $iri) {
10 years ago
// already an absolute IRI
if(strpos($iri, ':') !== false) {
return $iri;
}
// parse base if it is a string
if(is_string($base)) {
$base = jsonld_parse_url($base);
}
// parse given IRI
$rel = jsonld_parse_url($iri);
10 years ago
// start hierarchical part
$hierPart = $base['protocol'];
if($rel['authority']) {
$hierPart .= "//{$rel['authority']}";
}
else if($base['href'] !== '') {
$hierPart .= "//{$base['authority']}";
}
// per RFC3986 normalize
10 years ago
// IRI represents an absolute path
if(strpos($rel['path'], '/') === 0) {
10 years ago
$path = $rel['path'];
}
else {
$path = $base['path'];
// append relative path to the end of the last directory from base
if($rel['path'] !== '') {
$idx = strrpos($path, '/');
10 years ago
$idx = ($idx === false) ? 0 : $idx + 1;
$path = substr($path, 0, $idx);
if(strlen($path) > 0 && substr($path, -1) !== '/') {
$path .= '/';
}
$path .= $rel['path'];
10 years ago
}
}
// remove slashes and dots in path
$path = jsonld_remove_dot_segments($path, $hierPart !== '');
10 years ago
// add query and hash
if(isset($rel['query'])) {
$path .= "?{$rel['query']}";
}
if(isset($rel['fragment'])) {
$path .= "#{$rel['fragment']}";
}
$rval = $hierPart . $path;
if($rval === '') {
$rval = './';
}
10 years ago
return $rval;
}
/**
* Removes a base IRI from the given absolute IRI.
*
* @param mixed $base the base IRI.
* @param string $iri the absolute IRI.
*
* @return string the relative IRI if relative to base, otherwise the absolute
* IRI.
*/
function jsonld_remove_base($base, $iri) {
if(is_string($base)) {
$base = jsonld_parse_url($base);
}
// establish base root
$root = '';
if($base['href'] !== '') {
$root .= "{$base['protocol']}//{$base['authority']}";
}
// support network-path reference with empty base
else if(strpos($iri, '//') === false) {
$root .= '//';
}
// IRI not relative to base
if($root === '' || strpos($iri, $root) !== 0) {
return $iri;
}
// remove root from IRI
$rel = jsonld_parse_url(substr($iri, strlen($root)));
// remove path segments that match
$base_segments = explode('/', $base['normalizedPath']);
$iri_segments = explode('/', $rel['normalizedPath']);
while(count($base_segments) > 0 && count($iri_segments) > 0) {
if($base_segments[0] !== $iri_segments[0]) {
break;
}
array_shift($base_segments);
array_shift($iri_segments);
}
// use '../' for each non-matching base segment
$rval = '';
if(count($base_segments) > 0) {
// don't count the last segment if it isn't a path (doesn't end in '/')
// don't count empty first segment, it means base began with '/'
if(substr($base['normalizedPath'], -1) !== '/' ||
$base_segments[0] === '') {
array_pop($base_segments);
}
foreach($base_segments as $segment) {
$rval .= '../';
}
}
// prepend remaining segments
$rval .= implode('/', $iri_segments);
// add query and hash
if(isset($rel['query'])) {
$rval .= "?{$rel['query']}";
}
if(isset($rel['fragment'])) {
$rval .= "#{$rel['fragment']}";
}
if($rval === '') {
$rval = './';
}
return $rval;
}
/**
* A JSON-LD processor.
*/
class JsonLdProcessor {
/** XSD constants */
const XSD_BOOLEAN = 'http://www.w3.org/2001/XMLSchema#boolean';
const XSD_DOUBLE = 'http://www.w3.org/2001/XMLSchema#double';
const XSD_INTEGER = 'http://www.w3.org/2001/XMLSchema#integer';
const XSD_STRING = 'http://www.w3.org/2001/XMLSchema#string';
/** RDF constants */
const RDF_FIRST = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#first';
const RDF_REST = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#rest';
const RDF_NIL = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#nil';
const RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
const RDF_LANGSTRING =
'http://www.w3.org/1999/02/22-rdf-syntax-ns#langString';
/** Restraints */
const MAX_CONTEXT_URLS = 10;
/** Processor-specific RDF dataset parsers. */
protected $rdfParsers = null;
/**
* Constructs a JSON-LD processor.
*/
public function __construct() {}
/**
* Performs JSON-LD compaction.
*
* @param mixed $input the JSON-LD object to compact.
* @param mixed $ctx the context to compact with.
* @param assoc $options the compaction options.
* [base] the base IRI to use.
* [compactArrays] true to compact arrays to single values when
* appropriate, false not to (default: true).
* [graph] true to always output a top-level graph (default: false).
* [skipExpansion] true to assume the input is expanded and skip
* expansion, false not to, defaults to false.
* [activeCtx] true to also return the active context used.
* [documentLoader(url)] the document loader.
*
* @return mixed the compacted JSON-LD output.
*/
public function compact($input, $ctx, $options) {
if($ctx === null) {
throw new JsonLdException(
'The compaction context must not be null.',
'jsonld.CompactError');
}
// nothing to compact
if($input === null) {
return null;
}
self::setdefaults($options, array(
'base' => is_string($input) ? $input : '',
'compactArrays' => true,
'graph' => false,
'skipExpansion' => false,
'activeCtx' => false,
'documentLoader' => 'jsonld_default_document_loader'));
if($options['skipExpansion'] === true) {
$expanded = $input;
}
else {
// expand input
try {
$expanded = $this->expand($input, $options);
}
catch(JsonLdException $e) {
throw new JsonLdException(
'Could not expand input before compaction.',
'jsonld.CompactError', null, $e);
}
}
// process context
$active_ctx = $this->_getInitialContext($options);
try {
$active_ctx = $this->processContext($active_ctx, $ctx, $options);
}
catch(JsonLdException $e) {
throw new JsonLdException(
'Could not process context before compaction.',
'jsonld.CompactError', null, $e);
}
// do compaction
$compacted = $this->_compact($active_ctx, null, $expanded, $options);
if($options['compactArrays'] &&
!$options['graph'] && is_array($compacted)) {
// simplify to a single item
if(count($compacted) === 1) {
$compacted = $compacted[0];
}
// simplify to an empty object
else if(count($compacted) === 0) {
$compacted = new stdClass();
}
}
10 years ago
// always use array if graph option is on
else if($options['graph']) {
$compacted = self::arrayify($compacted);
}
// follow @context key
if(is_object($ctx) && property_exists($ctx, '@context')) {
$ctx = $ctx->{'@context'};
}
// build output context
$ctx = self::copy($ctx);
$ctx = self::arrayify($ctx);
// remove empty contexts
$tmp = $ctx;
$ctx = array();
foreach($tmp as $v) {
if(!is_object($v) || count(array_keys((array)$v)) > 0) {
$ctx[] = $v;
}
}
// remove array if only one context
$ctx_length = count($ctx);
$has_context = ($ctx_length > 0);
if($ctx_length === 1) {
$ctx = $ctx[0];
}
// add context and/or @graph
if(is_array($compacted)) {
// use '@graph' keyword
$kwgraph = $this->_compactIri($active_ctx, '@graph');
$graph = $compacted;
$compacted = new stdClass();
if($has_context) {
$compacted->{'@context'} = $ctx;
}
$compacted->{$kwgraph} = $graph;
}
else if(is_object($compacted) && $has_context) {
// reorder keys so @context is first
$graph = $compacted;
$compacted = new stdClass();
$compacted->{'@context'} = $ctx;
foreach($graph as $k => $v) {
$compacted->{$k} = $v;
}
}
if($options['activeCtx']) {
return array('compacted' => $compacted, 'activeCtx' => $active_ctx);
}
return $compacted;
}
/**
* Performs JSON-LD expansion.
*
* @param mixed $input the JSON-LD object to expand.
* @param assoc $options the options to use:
* [base] the base IRI to use.
* [expandContext] a context to expand with.
* [keepFreeFloatingNodes] true to keep free-floating nodes,
* false not to, defaults to false.
* [documentLoader(url)] the document loader.
*
* @return array the expanded JSON-LD output.
*/
public function expand($input, $options) {
self::setdefaults($options, array(
'base' => is_string($input) ? $input : '',
'keepFreeFloatingNodes' => false,
'documentLoader' => 'jsonld_default_document_loader'));
// if input is a string, attempt to dereference remote document
if(is_string($input)) {
$remote_doc = $options['documentLoader']($input);
}
else {
$remote_doc = (object)array(
'contextUrl' => null,
'documentUrl' => null,
'document' => $input);
}
// build meta-object and retrieve all @context urls
$input = (object)array(
'document' => self::copy($input),
'remoteContext' => (object)array(
'@context' => $remote_doc->contextUrl));
if(isset($options['expandContext'])) {
$expand_context = self::copy($options['expandContext']);
if(is_object($expand_context) &&
property_exists($expand_context, '@context')) {
$input->expandContext = $expand_context;
}
else {
$input->expandContext = (object)array('@context' => $expand_context);
}
}
// retrieve all @context URLs in the input
try {
$this->_retrieveContextUrls(
$input, new stdClass(), $options['documentLoader'], $options['base']);
}
catch(Exception $e) {
10 years ago
throw new JsonLdException(
'Could not perform JSON-LD expansion.',
'jsonld.ExpandError', null, $e);
}
$active_ctx = $this->_getInitialContext($options);
$document = $input->document;
$remote_context = $input->remoteContext->{'@context'};
// process optional expandContext
if(property_exists($input, 'expandContext')) {
$active_ctx = self::_processContext(
$active_ctx, $input->expandContext, $options);
}
// process remote context from HTTP Link Header
if($remote_context) {
$active_ctx = self::_processContext(
$active_ctx, $remote_context, $options);
}
// do expansion
$expanded = $this->_expand($active_ctx, null, $document, $options, false);
// optimize away @graph with no other properties
if(is_object($expanded) && property_exists($expanded, '@graph') &&
count(array_keys((array)$expanded)) === 1) {
$expanded = $expanded->{'@graph'};
}
else if($expanded === null) {
$expanded = array();