Class: Services_Yadis

Source Location: /Services_Yadis-0.2.2/Yadis.php

Class Overview

Services_Yadis class

Author(s):

Pádraic Brady (http://blog.astrumfutura.com)

Inherited Variables

Inherited Methods

Class Details

[line 99]
Services_Yadis class

Services_Yadis will provide a method of Service Discovery implemented in accordance with the Yadis Specification 1.0. This describes a protocol for locating an XRD document which details Services available. The XRD is typically specific to a single user, identified by their Yadis ID. Services_Yadis_XRDS will be a wrapper which is responsible for parsing and presenting an iterable list of Services_Yadis_Service objects holding the data for each specific Service discovered.

Note that class comments cannot substitute for a full understanding of the rules and nuances required to implement the Yadis protocol. Where doubt exists, refer to the Yadis Specification 1.0 at: http://yadis.org/papers/yadis-v1.0.pdf Departures from the specification should be regarded as bugs ;).

Example usage:

Example 1: OpenID Service Discovery

$openid = 'http://padraic.astrumfutura.com'; $yadis = new Services_Yadis($openid); $yadis->addNamespace('openid', 'http://openid.net/xmlns/1.0'); $serviceList = $yadis->discover();

foreach ($serviceList as $service) { $types = $service->getTypes(); echo $types[0], ' at ', implode(', ', $service->getUris()), PHP_EOL; echo 'Priority is ', $service->->getPriority(), PHP_EOL; }

Possible Result @index[0] (indicates we may send Auth 2.0 requests for OpenID):

http://specs.openid.net/auth/2.0/server at http://www.myopenid.com/server Priority is 0

Author: Pádraic Brady (http://blog.astrumfutura.com)
License: New BSD License

[ Top ]

Class Variables

$_httpRequest = null

[line 198]

HTTP_Request object utilised by this class if externally set

Access: protected

Type:

HTTP_Request

[ Top ]

$_httpRequestOptions = null

[line 191]

Access: protected

Type:

mixed

[ Top ]

$_metaHttpEquivResponse = null

[line 137]

Holds the first response received during Service Discovery.

This is required to allow certain Service specific fallback methods. For example, OpenID allows a Yadis fallback which relies on seeking a set of appropriate <link> elements.

Access: protected

Type:

string

[ Top ]

$_metaHttpEquivUrl = ''

[line 146]

A URL parsed from a HTML document's <meta> element inserted in accordance with the Yadis Specification and which points to a Yadis XRD document.

Access: protected

Type:

string

[ Top ]

$_namespace = null

[line 163]

Instance of Services_Yadis_Xrds_Namespace for managing namespaces associated with an XRDS document.

Access: protected

Type:

Services_Yadis_Xrds_Namespace

[ Top ]

$_validHtmlContentTypes = array(
        'text/html',
        'application/xhtml+xml',
        'application/xml',
        'text/xml'
    )

[line 174]

Array of valid HTML Content-Types. Required since Yadis states agents must parse a document if received as the first response and with an MIME type indicating HTML or XHTML. Listed in order of priority, with HTML taking priority over XHTML.

Link: http://www.w3.org/International/articles/serving-xhtml/Overview.en.php
Access: protected

Type:

array

[ Top ]

$_xrdsLocationHeaderUrl = ''

[line 155]

A URI parsed from an X-XRDS-Location response-header. This value must point to a Yadis XRD document otherwise the Yadis discovery process should be considered to have failed.

Access: protected

Type:

string

[ Top ]

$_xriIdentifiers = array(
'=', '$', '!', '@', '+'
)

[line 187]

Access: protected

Type:

mixed

[ Top ]

$_yadisId = ''

[line 117]

The current Yadis ID; this is the raw form initially submitted prior to any transformation/validation as an URL. This *may* allow IRI support in the future given IRIs map to URIs and adoption of the IRI standard and are entering common use internationally.

Access: protected

Type:

string

[ Top ]

$_yadisUrl = ''

[line 126]

The current Yadis URL; this is a URL either validated or transformed from the initial Yadis ID. This URL is used to make the initial HTTP GET request during Service Discovery.

Access: protected

Type:

string

[ Top ]

Method Detail

__construct (Constructor) [line 212]

Services_Yadis __construct(
[string
$yadisId = null], [array
$namespaces = null])

Class Constructor

Allows settings of the initial Yadis ID (an OpenID URL for example) and an optional list of additional namespaces. For example, OpenID uses a namespace such as: xmlns:openid="http://openid.net/xmlns/1.0" Namespaces are assigned to a Services_Yadis_Xrds_Namespace container object to be passed more easily to other objects being

Access: public

Parameters:

string	`$yadisId`	—
array	`$namespaces`	—

[ Top ]

addNamespace [line 361]

Services_Yadis addNamespace(
string
$namespace, string
$namespaceUrl)

Add a single namespace to be utilised by the XML parser when it receives a valid XRD document.

Access: public

Parameters:

string	`$namespace`	—
string	`$namespaceUrl`	—

[ Top ]

addNamespaces [line 347]

Services_Yadis addNamespaces(
array
$namespaces)

Add a list (array) of additional namespaces to be utilised by the XML parser when it receives a valid XRD document.

Access: public

Parameters:

array $namespaces —

[ Top ]

discover [line 396]

Services_Yadis_Xrds|boolean discover(
)

Performs Service Discovery, i.e. the requesting and parsing of a valid Yadis (XRD) document into a list of Services and Service Data. The return value will be an instance of Services_Yadis_Xrds which will implement SeekableIterator. Returns FALSE on failure.

Throws: Services_Yadis_Exception
Access: public

[ Top ]

getHttpRequest [line 488]

void getHttpRequest(
HTTP_Request
$request)

Setter for custom HTTP_Request type object

Access: public

Parameters:

HTTP_Request $request —

[ Top ]

getHttpRequestOptions [line 243]

array getHttpRequestOptions(
)

Get options to be passed to the PEAR HTTP_Request constructor

Access: public

[ Top ]

getNamespace [line 372]

string|null getNamespace(

$namespace)

Return the value of a specific namespace.

Access: public

Parameters:

$namespace —

[ Top ]

getNamespaces [line 382]

array getNamespaces(
)

Returns an array of all currently set namespaces.

Access: public

[ Top ]

getUserResponse [line 463]

string|boolean getUserResponse(
)

Return the very first response received when using a valid Yadis URL.

This is important for Services, like OpenID, which can attempt a fallback solution in case Yadis fails, and the response came from a user's personal URL acting as an alias.

Access: public

[ Top ]

getYadisId [line 270]

string getYadisId(
)

Returns the original Yadis ID string set for this class.

Access: public

[ Top ]

getYadisUrl [line 331]

string getYadisUrl(
)

Returns the Yadis URL. This will usually be identical to the Yadis ID, unless the Yadis ID (in the future) was one of IRI, XRI or i-name which required transformation to a valid URI.

Access: public

[ Top ]

setHttpRequest [line 477]

void setHttpRequest(
HTTP_Request
$request)

Setter for custom HTTP_Request type object

Access: public

Parameters:

HTTP_Request $request —

[ Top ]

setHttpRequestOptions [line 233]

void setHttpRequestOptions(
array
$options)

Set options to be passed to the PEAR HTTP_Request constructor

Access: public

Parameters:

array $options —

[ Top ]

setYadisId [line 259]

void setYadisId(
string
$yadisId)

A Yadis ID is usually an URL, but can also include an IRI, or XRI i-name.

The initial version will support URLs as standard before examining options for supporting alternatives (IRI,XRI,i-name) since they require additional validation and conversion steps (e.g. Punycode for IRI) before use.

Note: The current Validate classes currently do not have complete IDNA validation support for Internationalised Domain Names. To be addressed.

Access: public

Parameters:

string $yadisId —

[ Top ]

setYadisUrl [line 288]

Services_Yadis setYadisUrl(
string
$yadisId)

Attempts to create a valid URI based on the value of the parameter which would typically be the Yadis ID.

Note: This currently only supports XRI transformations.

Throws: Services_Yadis_Exception
Access: public

Parameters:

string $yadisId —

[ Top ]

_get [line 522]

HTTP_Request _get(
string
$url)

Use the HTTP_Request to issue an HTTP GET request carrying the "Accept" header value of "application/xrds+xml". This can allow servers to quickly respond with a valid XRD document rather than forcing the client to follow the X-XRDS-Location bread crumb trail.

Access: protected

Parameters:

string $url —

[ Top ]

_getResponseType [line 501]

integer _getResponseType(
HTTP_Request
$request)

Run any instance of HTTP_Request through a set of filters to determine the Yadis Response type which in turns determines how the response should be reacted to or dealt with.

Access: protected

Parameters:

HTTP_Request $request —

[ Top ]

_isMetaHttpEquiv [line 590]

boolean _isMetaHttpEquiv(
HTTP_Request
$request)

Assuming this user is hosting a third party sourced identity under an alias personal URL, we'll need to check if the website's HTML body has a http-equiv meta element with a content attribute pointing to where we can fetch the XRD document.

Throws: Services_Yadis_Exception
Access: protected

Parameters:

HTTP_Request $request —

[ Top ]

_isXrdsContentType [line 572]

boolean _isXrdsContentType(
HTTP_Request
$request)

Checks whether the Response contains the XRDS resource. It should, per the specifications always be served as application/xrds+xml

Access: protected

Parameters:

HTTP_Request $request —

[ Top ]

_isXrdsLocationHeader [line 547]

boolean _isXrdsLocationHeader(
HTTP_Request
$request)

Checks whether the Response contains headers which detail where we can find the XRDS resource for this user. If exists, the value is set to the private $_xrdsLocationHeaderUrl property.

Access: protected

Parameters:

HTTP_Request $request —

[ Top ]

_parseXrds [line 639]

Services_Yadis_Xrds|boolean _parseXrds(
string
$xrdsDocument)

Creates a new Services_Yadis_Xrds object which uses SimpleXML to parse the XML into a list of Iterable Services_Yadis_Service objects.

Access: protected

Parameters:

string $xrdsDocument —

[ Top ]

Class: Services_Yadis

Class Overview

Author(s):

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

Class Variables

$_httpRequest = null

$_httpRequestOptions = null

$_metaHttpEquivResponse = null

$_metaHttpEquivUrl = ''

$_namespace = null

$_validHtmlContentTypes = array( 'text/html', 'application/xhtml+xml', 'application/xml', 'text/xml' )

$_xrdsLocationHeaderUrl = ''

$_xriIdentifiers = array( '=', '$', '!', '@', '+' )

$_yadisId = ''

$_yadisUrl = ''

Method Detail

__construct (Constructor) [line 212]

Parameters:

addNamespace [line 361]

Parameters:

addNamespaces [line 347]

Parameters:

discover [line 396]

getHttpRequest [line 488]

Parameters:

getHttpRequestOptions [line 243]

getNamespace [line 372]

Parameters:

getNamespaces [line 382]

getUserResponse [line 463]

getYadisId [line 270]

getYadisUrl [line 331]

setHttpRequest [line 477]

Parameters:

setHttpRequestOptions [line 233]

Parameters:

setYadisId [line 259]

Parameters:

setYadisUrl [line 288]

Parameters:

_get [line 522]

Parameters:

_getResponseType [line 501]

Parameters:

_isMetaHttpEquiv [line 590]

Parameters:

_isXrdsContentType [line 572]

Parameters:

_isXrdsLocationHeader [line 547]

Parameters:

_parseXrds [line 639]

Parameters:

$_validHtmlContentTypes = array(
'text/html',
'application/xhtml+xml',
'application/xml',
'text/xml'
)

$_xriIdentifiers = array(
'=', '$', '!', '@', '+'
)