README

PHP library to parse and generate Extensible Resource Descriptor (XRD) Version 1.0 files. It supports loading and saving XML (XRD) and JSON (JRD) markup.

XRD and JRD files are used for .well-known/host-meta files as standardized in RFC 6415: Web Host Metadata.

Webfinger, based on JRD, can be used to discover information about users by just their e-mail address, e.g. their OpenID provider URL.

The XRD format supercedes the XRDS format defined in XRI 2.0, which is used in the Yadis communications protocol.

Contents

Examples
Error handling
TODO
Links

Examples

Loading XRD files

Load from file

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
try {
    $xrd->loadFile('/path/to/my.xrd', 'xml');
} catch (XML_XRD_Exception $e) {
    die('Loading XRD file failed: '  . $e->getMessage());
}

Load from string

<?php
$myxrd = <<<XRD
<?xml version="1.0"?>
<XRD>
 ...
XRD;

require_once 'XML/XRD.php';
$xrd = new XML_XRD();
try {
    $xrd->loadString($myxrd, 'xml');
} catch (XML_XRD_Exception $e) {
    die('Loading XRD string failed: '  . $e->getMessage());
}

Verification

Verify subject

Check if the XRD file really describes the resource/URL that we requested the XRD for:

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
$xrd->loadFile('http://example.org/.well-known/host-meta');
if (!$xrd->describes('http://example.org/')) {
    die('XRD document is not the correct one for http://example.org/');
}

The <subject> and all <alias> tags are checked.

Link finding

Get all links

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
$xrd->loadFile('http://example.org/.well-known/host-meta');
foreach ($xrd as $link) {
    echo $link->rel . ': ' . $link->href . "\n";
}

Get link by relation

Returns the first link that has the given relation:

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
$xrd->loadFile('http://example.org/.well-known/host-meta');
$idpLink = $xrd->get('lrdd');
echo $idpLink->rel . ': ' . $idpLink->href . "\n";

Get link by relation + optional type

If no link with the given type is found, the first link with the correct relation and an empty type will be returned:

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
$xrd->loadFile('http://example.org/.well-known/host-meta');
$link = $xrd->get('lrdd', 'application/xrd+xml');
echo $link->rel . ': ' . $link->href . "\n";

Get link by relation + type

The relation and the type both need to match exactly:

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
$xrd->loadFile('http://example.org/.well-known/host-meta');
$link = $xrd->get('lrdd', 'application/xrd+xml', false);
echo $link->rel . ': ' . $link->href . "\n";

Get all links by relation

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
$xrd->loadFile('http://example.org/.well-known/host-meta');
foreach ($xrd->getAll('lrdd') as $link) {
    echo $link->rel . ': ' . $link->href . "\n";
}

Properties

Get a single property

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
$xrd->loadFile('http://example.org/.well-known/host-meta');
if (isset($xrd['http://spec.example.net/type/person'])) {
    echo $xrd['http://spec.example.net/type/person'] . "\n";
}

Get all properties

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
$xrd->loadFile('http://example.org/.well-known/host-meta');
foreach ($xrd->getProperties() as $property) {
    echo $property->type . ': ' . $property->value . "\n";
}

Get all properties of a type

<?php
require_once 'XML/XRD.php';
$xrd = new XML_XRD();
$xrd->loadFile('http://example.org/.well-known/host-meta');
foreach ($xrd->getProperties('http://spec.example.net/type/person') as $property) {
    echo $property->type . ': ' . $property->value . "\n";
}

Working with Links

Accessing link attributes

<?php
$link = $xrd->get('http://specs.openid.net/auth/2.0/provider');

$title = $link->getTitle('de');
$url   = $link->href;
$urlTemplate = $link->template;
$mimetype    = $link->type;

Additional link properties

Works just like properties in the XRD document:

<?php
$link = $xrd->get('http://specs.openid.net/auth/2.0/provider');
$prop = $link['foo'];

Generating XRD files

.well-known/host-meta

As described by RFC 6415:

<?php
require_once 'XML/XRD.php';
$x = new XML_XRD();
$x->subject = 'example.org';
$x->aliases[] = 'example.com';
$x->links[] = new XML_XRD_Element_Link(
    'lrdd', 'http://example.org/gen-lrdd.php?a={uri}',
    'application/xrd+xml', true
);
echo $x->to('xml');
?>

If you want a JSON file for JRD:

echo $x->to('json');

Webfinger file

<?php
require_once 'XML/XRD.php';
$x = new XML_XRD();
$x->subject = 'user@example.org';

//add link to the user's OpenID
$x->links[] = new XML_XRD_Element_Link(
    'http://specs.openid.net/auth/2.0/provider',
    'http://id.example.org/user'
);
//add link to user's home page
$x->links[] = new XML_XRD_Element_Link(
    'http://xmlns.com/foaf/0.1/homepage',
    'http://example.org/~user/'
);

echo $x->to('jrd');
?>

When loading a file, exceptions of type XML_XRD_Exception may be thrown. All other parts of the code do not throw exceptions but fail gracefully by returning null, e.g. when a property does not exist.

Using loadFile() may result in PHP warnings like:

Warning: simplexml_load_file(https://example.org/) failed to open stream: Connection refused

This cannot be prevented properly, so you either have to silence it with @ or fetch the file manually and use loadString().

TODO

XML signature verification
(very optional) XRDS (multiple XRD)?

pear / xml_xrd

Maintainers

Details