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
  • Loading XRD files
    • Load from file
    • Load from string
  • Verification
    • Verify subject
  • Link finding
    • Get all links
    • Get link by relation
    • Get link by relation + optional type
    • Get link by relation + type
    • Get all links by relation
  • Properties
    • Get a single property
    • Get all properties
    • Get all properties of a type
  • Working with Links
    • Accessing link attributes
    • Additional link properties
  • Generating XRD files
    • .well-known/host-meta
    • Webfinger file
• 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');
?>

Error handling

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)?

Links

• XRD 1.0 standard specification
• OASIS XRI committee
• WebFinger protocol draft
• WebFinger: Common Link relations
• More link relations
• RFC 5785: Defining Well-Known Uniform Resource Identifiers
• RFC 6415: Web Host Metadata
• WebFinger draft