Home » Networking » Net_WebFinger » Manual

How to use the package

At first, include the PHP file, create a Net_WebFinger object and run finger() on it, passing the identifier (often the e-mail address, always user@host). finger() returns a Net_WebFinger_Reaction object which you can use to get links from.

<?php
require_once 'Net_WebFinger.php';
$wf = new Net_WebFinger();
$reaction = $wf->finger('user@example.org');
?>

Now you have access to the links, errors and security information.

Link access

The Net_WebFinger_Reaction object you get from Net_WebFinger::finger() lets you access the the user's links in three ways:

• By one of the short name properties.
• The get() method.
• Iterate with foreach() over the reaction object.

Short name properties

Often used link relations have a dedicated "short name" in Net_WebFinger to make accessing the link easy:

You can use each short name as property on the reaction object like this:

<?php
require_once 'Net/WebFinger.php';
$wf  = new Net_WebFinger();
$react = $wf->finger('user@example.org');
if ($react->openid !== null) {
    echo 'OpenID provider found: ' . $react->openid . "\n";
}
?>

Net_WebFinger_Reaction::get()

Net_WebFinger_Reaction::get() can always be used to access any link, especially those that have no short name. Just pass the URL of the link relation.

It returns NULL in case the link is not available, and the string if its there.

<?php
require_once 'Net/WebFinger.php';
$wf = new Net_WebFinger();
$react = $wf->finger('user@example.org');
$openIdProvider = $react->get('http://specs.openid.net/auth/2.0/provider');
if ($openIdProvider !== null) {
    echo 'OpenID provider found: ' . $openIdProvider . "\n";
}
?>

foreach()

You may use foreach() on the Net_WebFinger_Reaction object to get all links.

This will give you a XML_XRD_Element_Link object for each single link.

<?php
require_once 'Net/WebFinger.php';
$wf = new Net_WebFinger();
$react = $wf->finger('user@example.org');
foreach ($react as $link) {
    echo 'Link: ' . $link->rel . ' to ' . $link->href . "\n";
}
?>

Security

The underlying XRD files will be retrieved via SSL when possible, with fallback to normal HTTP. In the latter case, the XRD files need to have valid signatures in order to be seen as secure.

The XRD subject is also verified. When it does not match the host name of the email address, then the information are seen as insecure.

You should not trust the information if they are not secure.

<?php
require_once 'Net/WebFinger.php';
$wf  = new Net_WebFinger();
$react = $wf->finger('user@example.org');
if (!$react->secure) {
    die("Those data may not be trusted\n");
}
?>

You often still want to use the data, since not all hosts have SSL enabled.

Error handling

Net_WebFinger does not throw any exceptions. If an error occurs during WebFinger discovery, it is stored as Net_WebFinger_Error object in the reaction's $error property. If you really need it, you can access it there.

When accessing links that are not defined, you will get a NULL value instead of a string.

Caching

With caching, all retrieved XRD/JRD files will be stored locally, which leads to faster lookup times when the same identifier (email address) is loaded again.

You should use caching when your application often does WebFinger requests. For older RFC 6415-based webfinger implementations, it reduces the number of HTTP requests to the same server from 2 to 1 for each lookup.

<?php
require_once 'Net/WebFinger.php';
require_once 'Cache.php';
$wf = new Net_WebFinger();
$wf->setCache(
    new Cache('file', array('cache_dir' => sys_get_temp_dir() . '/myapp'))
);
$react = $wf->finger('user@example.org');
$openIdProvider = $react->get('http://specs.openid.net/auth/2.0/provider');
?>

Custom HTTP adapters

By default, the HTTP(S) XRD files are loaded by XML_XRD internally using file_get_contents.

If you want to set custom HTTP request headers or modify redirection handling, you may use an own HTTP adapter that will be used to fetch the files:

<?php
require_once 'HTTP/Request2.php';
require_once 'Net/WebFinger.php';

$req = new HTTP_Request2();
$req->setConfig('follow_redirects', true);//needed for full compatibility
$req->setHeader('User-Agent', 'MyApp 1.42');

$wf = new Net_WebFinger();
$wf->setHttpClient($req);
$react = $wf->finger('foo@example.org');
?>

References

• Current specification: draft-ietf-appsawg-webfinger-13
• Early WebFinger specification
• Common link relations
• XML_XRD package to load and create the XRD files; may be used to serve WebFinger on your own server.
• WebFinger mailing list