Class: Services_Yadis

Source Location: /Services_Yadis-0.3.0/Yadis.php

Class Overview

Services_Yadis class

Author(s):

Pádraic Brady <padraic.brady at yahoo.com>

Inherited Variables

Inherited Methods

Class Details

[line 98]
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 <padraic.brady@yahoo.com>
Link: http://pear.php.net/Services_Yadis
License: New BSD License

[ Top ]

Class Variables

$httpRequest = null

[line 197]

HTTP_Request object utilised by this class if externally set

Access: protected

Type:

HTTP_Request

[ Top ]

$httpRequestOptions = array()

[line 190]

Access: protected

Type:

mixed

[ Top ]

$metaHttpEquivResponse = null

[line 136]

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:

HTTP_Request

[ Top ]

$metaHttpEquivUrl = ''

[line 145]

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 162]

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 173]

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 154]

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 186]

Access: protected

Type:

mixed

[ Top ]

$yadisId = ''

[line 116]

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 125]

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 213]

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

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`	—	Optional Yadis ID
array	`$namespaces`	—	Optional array of namespaces

[ Top ]

addNamespace [line 362]

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`	—	The namespace name
string	`$namespaceUrl`	—	The namespace url

[ 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 — Array of namespaces

[ Top ]

discover [line 399]

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 ]

get [line 537]

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 — URL

[ Top ]

getHttpRequest [line 501]

HTTP_Request getHttpRequest(
)

Gets the HTTP_Request object

Access: public

[ Top ]

getHttpRequestOptions [line 240]

array getHttpRequestOptions(
)

Get options to be passed to the PEAR HTTP_Request constructor

Access: public

[ Top ]

getNamespace [line 375]

string|null getNamespace(
string
$namespace)

Return the value of a specific namespace.

Access: public

Parameters:

string $namespace — Namespace name

[ Top ]

getNamespaces [line 385]

array getNamespaces(
)

Returns an array of all currently set namespaces.

Access: public

[ Top ]

getResponseType [line 515]

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 — Instance of HTTP_Request

[ Top ]

getUserResponse [line 476]

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 269]

string getYadisId(
)

Returns the original Yadis ID string set for this class.

Access: public

[ Top ]

getYadisUrl [line 329]

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 ]

isMetaHttpEquiv [line 614]

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 — Instance of HTTP_Request

[ Top ]

isXrdsContentType [line 592]

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 — Instance of HTTP_Request

[ Top ]

isXrdsLocationHeader [line 565]

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 — Instance of HTTP_Request

[ Top ]

parseXrds [line 672]

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 — The plaintext XRDS document

[ Top ]

setHttpRequest [line 491]

void setHttpRequest(
HTTP_Request
$request)

Setter for custom HTTP_Request type object

Access: public

Parameters:

HTTP_Request $request — Instance of HTTP_Request

[ Top ]

setHttpRequestOptions [line 229]

Services_Yadis setHttpRequestOptions(
array
$options)

Set options to be passed to the PEAR HTTP_Request constructor

Access: public

Parameters:

array $options — Array of options for HTTP_Request

[ Top ]

setYadisId [line 258]

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 — The Yadis ID

[ Top ]

setYadisUrl [line 289]

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 — The Yadis ID

[ Top ]

Class: Services_Yadis

Class Overview

Author(s):

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

Class Variables

$httpRequest = null

$httpRequestOptions = array()

$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 213]

Parameters:

addNamespace [line 362]

Parameters:

addNamespaces [line 347]

Parameters:

discover [line 399]

get [line 537]

Parameters:

getHttpRequest [line 501]

getHttpRequestOptions [line 240]

getNamespace [line 375]

Parameters:

getNamespaces [line 385]

getResponseType [line 515]

Parameters:

getUserResponse [line 476]

getYadisId [line 269]

getYadisUrl [line 329]

isMetaHttpEquiv [line 614]

Parameters:

isXrdsContentType [line 592]

Parameters:

isXrdsLocationHeader [line 565]

Parameters:

parseXrds [line 672]

Parameters:

setHttpRequest [line 491]

Parameters:

setHttpRequestOptions [line 229]

Parameters:

setYadisId [line 258]

Parameters:

setYadisUrl [line 289]

Parameters:

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

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