 |
API Joomla 1.5.26
Documentation des API du CMS Joomla en version 1.5
|
|
API Joomla 1.5.26
Documentation des API du CMS Joomla en version 1.5
|
This module contains code for dealing with associations between consumers and servers.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
private private private This class represents an association between a server and a consumer. In general, users of this library will never see instances of this object. The only exception is if you implement a custom Auth_OpenID_OpenIDStore.
If you do implement such a store, it will need to store the values of the handle, secret, issued, lifetime, and assoc_type instance variables.
A session negotiator controls the allowed and preferred association types and association session types. Both the Auth_OpenID_Consumer and Auth_OpenID_Server use negotiators when creating associations.
You can create and use negotiators if you:
It is up to you to set a policy for what kinds of associations to accept. By default, the library will make any kind of association that is allowed in the OpenID 2.0 specification.
Use of negotiators in the library =================================
When a consumer makes an association request, it calls getAllowedType to get the preferred association type and association session type.
The server gets a request for a particular association/session type and calls isAllowed to determine if it should create an association. If it is supported, negotiation is complete. If it is not, the server calls getAllowedType to get an allowed association type to return to the consumer.
If the consumer gets an error response indicating that the requested association/session type is not supported by the server that contains an assocation/session type to try, it calls isAllowed to determine if it should try again with the given combination of association/session type.
Implements the OpenID attribute exchange specification, version 1.0 as of svn revision 370 from openid.net svn.
AX utility class.
Results from data that does not meet the attribute exchange 1.0 specification
Abstract class containing common code for attribute exchange messages.
Represents a single attribute in an attribute exchange request. This should be added to an AXRequest object in order to request the attribute.
An attribute exchange 'fetch_request' message. This message is sent by a relying party when it wishes to obtain attributes about the subject of an OpenID authentication request.
An abstract class that implements a message that has attribute keys and values. It contains the common code between fetch_response and store_request.
A fetch_response attribute exchange message.
A store request attribute exchange message representation.
An indication that the store request was processed along with this OpenID transaction. Use make(), NOT the constructor, to create response objects.
BigMath: A math library wrapper that abstracts out the underlying long integer library.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
private
Needed for random number generation Need Auth_OpenID::bytes(). The superclass of all big-integer math implementations private
Exposes BCmath math library functionality.
Auth_OpenID_BcMathWrapper wraps the functionality provided by the BCMath extension.
private
Exposes GMP math library functionality.
Auth_OpenID_GmpMathWrapper wraps the functionality provided by the GMP extension.
private
Auth_OpenID_getMathLib checks for the presence of long number extension modules and returns an instance of Auth_OpenID_MathWrapper which exposes the module's functionality.
Checks for the existence of an extension module described by the result of Auth_OpenID_math_extensions() and returns an instance of a wrapper for that extension module. If no extension module is found, an instance of Auth_OpenID_MathWrapper is returned, which wraps the native PHP integer implementation. The proper calling convention for this method is $lib =& Auth_OpenID_getMathLib().
This function checks for the existence of specific long number implementations in the following order: GMP followed by BCmath.
This module documents the main interface with the OpenID consumer library. The only part of the library which has to be used and isn't documented in full here is the store required to create an Auth_OpenID_Consumer instance. More on the abstract store type and concrete implementations of it that are provided in the documentation for the Auth_OpenID_Consumer constructor.
OVERVIEW
The OpenID identity verification process most commonly uses the following steps, as visible to the user of this library:
1. The user enters their OpenID into a field on the consumer's site, and hits a login button. 2. The consumer site discovers the user's OpenID server using the YADIS protocol. 3. The consumer site sends the browser a redirect to the identity server. This is the authentication request as described in the OpenID specification. 4. The identity server's site sends the browser a redirect back to the consumer site. This redirect contains the server's response to the authentication request.
The most important part of the flow to note is the consumer's site must handle two separate HTTP requests in order to perform the full identity check.
LIBRARY DESIGN
This consumer library is designed with that flow in mind. The goal is to make it as easy as possible to perform the above steps securely.
At a high level, there are two important parts in the consumer library. The first important part is this module, which contains the interface to actually use this library. The second is the Auth_OpenID_Interface class, which describes the interface to use if you need to create a custom method for storing the state this library needs to maintain between requests.
In general, the second part is less important for users of the library to know about, as several implementations are provided which cover a wide variety of situations in which consumers may use the library.
This module contains a class, Auth_OpenID_Consumer, with methods corresponding to the actions necessary in each of steps 2, 3, and 4 described in the overview. Use of this library should be as easy as creating an Auth_OpenID_Consumer instance and calling the methods appropriate for the action the site wants to take.
STORES AND DUMB MODE
OpenID is a protocol that works best when the consumer site is able to store some state. This is the normal mode of operation for the protocol, and is sometimes referred to as smart mode. There is also a fallback mode, known as dumb mode, which is available when the consumer site is not able to store state. This mode should be avoided when possible, as it leaves the implementation more vulnerable to replay attacks.
The mode the library works in for normal operation is determined by the store that it is given. The store is an abstraction that handles the data that the consumer needs to manage between http requests in order to operate efficiently and securely.
Several store implementation are provided, and the interface is fully documented so that custom stores can be used as well. See the documentation for the Auth_OpenID_Consumer class for more information on the interface for stores. The implementations that are provided allow the consumer site to store the necessary data in several different ways, including several SQL databases and normal files on disk.
There is an additional concrete store provided that puts the system in dumb mode. This is not recommended, as it removes the library's ability to stop replay attacks reliably. It still uses time-based checking to make replay attacks only possible within a small window, but they remain possible within that window. This store should only be used if the consumer site has no way to retain data between requests at all.
IMMEDIATE MODE
In the flow described above, the user may need to confirm to the lidentity server that it's ok to authorize his or her identity. The server may draw pages asking for information from the user before it redirects the browser back to the consumer's site. This is generally transparent to the consumer site, so it is typically ignored as an implementation detail.
There can be times, however, where the consumer site wants to get a response immediately. When this is the case, the consumer can put the library in immediate mode. In immediate mode, there is an extra response possible from the server, which is essentially the server reporting that it doesn't have enough information to answer the question yet.
USING THIS LIBRARY
Integrating this library into an application is usually a relatively straightforward process. The process should basically follow this plan:
Add an OpenID login field somewhere on your site. When an OpenID is entered in that field and the form is submitted, it should make a request to the your site which includes that OpenID URL.
First, the application should instantiate the Auth_OpenID_Consumer class using the store of choice (Auth_OpenID_FileStore or one of the SQL-based stores). If the application has a custom session-management implementation, an object implementing the Auth_Yadis_PHPSession interface should be passed as the second parameter. Otherwise, the default uses $_SESSION.
Next, the application should call the Auth_OpenID_Consumer object's 'begin' method. This method takes the OpenID URL. The 'begin' method returns an Auth_OpenID_AuthRequest object.
Next, the application should call the 'redirectURL' method of the Auth_OpenID_AuthRequest object. The 'return_to' URL parameter is the URL that the OpenID server will send the user back to after attempting to verify his or her identity. The 'trust_root' is the URL (or URL pattern) that identifies your web site to the user when he or she is authorizing it. Send a redirect to the resulting URL to the user's browser.
That's the first half of the authentication process. The second half of the process is done after the user's ID server sends the user's browser a redirect back to your site to complete their login.
When that happens, the user will contact your site at the URL given as the 'return_to' URL to the Auth_OpenID_AuthRequest::redirectURL call made above. The request will have several query parameters added to the URL by the identity server as the information necessary to finish the request.
Lastly, instantiate an Auth_OpenID_Consumer instance as above and call its 'complete' method, passing in all the received query arguments.
There are multiple possible return types possible from that method. These indicate the whether or not the login was successful, and include any additional information appropriate for their type.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
An OpenID consumer implementation that performs discovery and does session management. See the Consumer.php file documentation for more information.
A class implementing HMAC/DH-SHA1 consumer sessions.
A class implementing HMAC/DH-SHA256 consumer sessions.
A class implementing plaintext consumer sessions.
This class is the interface to the OpenID consumer logic. Instances of it maintain no per-request state, so they can be reused (or even used by multiple threads concurrently) as needed.
This class represents an authentication request from a consumer to an OpenID server.
The base class for responses from the Auth_OpenID_Consumer.
A response with a status of Auth_OpenID_SUCCESS. Indicates that this request is a successful acknowledgement from the OpenID server that the supplied URL is, indeed controlled by the requesting agent. This has three relevant attributes:
claimed_id - The identity URL that has been authenticated
signed_args - The arguments in the server's response that were signed and verified.
status - Auth_OpenID_SUCCESS.
A response with a status of Auth_OpenID_FAILURE. Indicates that the OpenID protocol has failed. This could be locally or remotely triggered. This has three relevant attributes:
claimed_id - The identity URL for which authentication was attempted, if it can be determined. Otherwise, null.
message - A message indicating why the request failed, if one is supplied. Otherwise, null.
status - Auth_OpenID_FAILURE.
A specific, internal failure used to detect type URI mismatch.
Exception that is raised when the server returns a 400 response code to a direct request.
A response with a status of Auth_OpenID_CANCEL. Indicates that the user cancelled the OpenID authentication request. This has two relevant attributes:
claimed_id - The identity URL for which authentication was attempted, if it can be determined. Otherwise, null.
status - Auth_OpenID_SUCCESS.
A response with a status of Auth_OpenID_SETUP_NEEDED. Indicates that the request was in immediate mode, and the server is unable to authenticate the user without further interaction.
claimed_id - The identity URL for which authentication was attempted.
setup_url - A URL that can be used to send the user to the server to set up for authentication. The user should be redirected in to the setup_url, either in the current window or in a new browser window. Null in OpenID 2.
status - Auth_OpenID_SETUP_NEEDED.
CryptUtil: A suite of wrapper utility functions for the OpenID library.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
private
The Auth_OpenID_DatabaseConnection class, which is used to emulate a PEAR database connection.
An empty base class intended to emulate PEAR connection functionality in applications that supply their own database abstraction mechanisms. See Auth_OpenID_SQLStore for more information. You should subclass this class if you need to create an SQL store that needs to access its database using an application's database abstraction layer instead of a PEAR database connection. Any subclass of Auth_OpenID_DatabaseConnection MUST adhere to the interface specified here.
The OpenID library's Diffie-Hellman implementation.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
private
The Diffie-Hellman key exchange class. This class relies on Auth_OpenID_MathLibrary to perform large number operations.
private
This file supplies a dumb store backend for OpenID servers and consumers.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
Import the interface for creating a new store class. This is a store for use in the worst case, when you have no way of saving state on the consumer site. Using this store makes the consumer vulnerable to replay attacks, as it's unable to use nonces. Avoid using this store if it is at all possible.
Most of the methods of this class are implementation details. Users of this class need to worry only about the constructor.
An interface for OpenID extensions.
Require the Message implementation. A base class for accessing extension request and response data for the OpenID 2 protocol.
This file supplies a Memcached store backend for OpenID servers and consumers.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
Require base class for creating a new interface. This is a filesystem-based store for OpenID associations and nonces. This store should be safe for use in concurrent systems on both windows and unix (excluding NFS filesystems). There are a couple race conditions in the system, but those failure cases have been set up in such a way that the worst-case behavior is someone having to try to log in a second time.
Most of the methods of this class are implementation details. People wishing to just use this store need only pay attention to the constructor.
This is the HMACSHA1 implementation for the OpenID library.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
private
This file specifies the interface for PHP OpenID store implementations.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
This is the interface for the store objects the OpenID library uses. It is a single class that provides all of the persistence mechanisms that the OpenID library needs, for both servers and consumers. If you want to create an SQL-driven store, please see then Auth_OpenID_SQLStore class.
Change: Version 2.0 removed the storeNonce, getAuthKey, and isDumb methods, and changed the behavior of the useNonce method to support one-way nonces.
OpenID protocol key-value/comma-newline format parsing and serialization
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
private
This file supplies a memcached store backend for OpenID servers and consumers.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
Import the interface for creating a new store class. This is a memcached-based store for OpenID associations and nonces.
As memcache has limit of 250 chars for key length, server_url, handle and salt are hashed with sha1().
Most of the methods of this class are implementation details. People wishing to just use this store need only pay attention to the constructor.
Extension argument processing code
An Auth_OpenID_Mapping maintains a mapping from arbitrary keys to arbitrary values. (This is unlike an ordinary PHP array, whose keys may be only simple scalars.)
Maintains a bijective map between namespace uris and aliases.
In the implementation of this object, null represents the global namespace as well as a namespace with no key.
A MySQL store.
Require the base class file. An SQL store that uses MySQL as its backend.
Nonce-related functionality.
This module implements a VERY limited parser that finds <link> tags in the head of HTML or XHTML documents and parses out their attributes according to the OpenID spec. It is a liberal parser, but it requires these things from the data in order to work:
From http://openid.net/specs.bml:
The parser ignores SGML comments and <![CDATA[blocks]]>. Both kinds of quoting are allowed for attributes.
The parser deals with invalid markup in these ways:
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
private
A PostgreSQL store.
Require the base class file. An SQL store that uses PostgreSQL as its backend.
OpenID server protocol and logic.
Overview
An OpenID server must perform three tasks:
1. Examine the incoming request to determine its nature and validity. 2. Make a decision about how to respond to this request. 3. Format the response according to the protocol.
The first and last of these tasks may performed by the Auth_OpenID_Server::decodeRequest() and Auth_OpenID_Server::encodeResponse methods. Who gets to do the intermediate task -- deciding how to respond to the request -- will depend on what type of request it is.
If it's a request to authenticate a user (a 'checkid_setup' or 'checkid_immediate' request), you need to decide if you will assert that this user may claim the identity in question. Exactly how you do that is a matter of application policy, but it generally involves making sure the user has an account with your system and is logged in, checking to see if that identity is hers to claim, and verifying with the user that she does consent to releasing that information to the party making the request.
Examine the properties of the Auth_OpenID_CheckIDRequest object, and if and when you've come to a decision, form a response by calling Auth_OpenID_CheckIDRequest::answer().
Other types of requests relate to establishing associations between client and server and verifing the authenticity of previous communications. Auth_OpenID_Server contains all the logic and data necessary to respond to such requests; just pass it to Auth_OpenID_Server::handleRequest().
OpenID Extensions
Do you want to provide other information for your users in addition to authentication? Version 1.2 of the OpenID protocol allows consumers to add extensions to their requests. For example, with sites using the Simple Registration Extension (http://www.openidenabled.com/openid/simple-registration-extension/), a user can agree to have their nickname and e-mail address sent to a site when they sign up.
Since extensions do not change the way OpenID authentication works, code to handle extension requests may be completely separate from the Auth_OpenID_Request class here. But you'll likely want data sent back by your extension to be signed. Auth_OpenID_ServerResponse provides methods with which you can add data to it which can be signed with the other data in the OpenID signature.
For example:
// when request is a checkid_* request
$response = $request->answer(true);
// this will a signed 'openid.sreg.timezone' parameter to the response
response.addField('sreg', 'timezone', 'America/Los_Angeles')Stores
The OpenID server needs to maintain state between requests in order to function. Its mechanism for doing this is called a store. The store interface is defined in Interface.php. Additionally, several concrete store implementations are provided, so that most sites won't need to implement a custom store. For a store backed by flat files on disk, see Auth_OpenID_FileStore. For stores based on MySQL, SQLite, or PostgreSQL, see the Auth_OpenID_SQLStore subclasses.
Upgrading
The keys by which a server looks up associations in its store have changed in version 1.2 of this library. If your store has entries created from version 1.0 code, you should empty it.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
An error class which gets instantiated and returned whenever an OpenID protocol error occurs. Be prepared to use this in place of an ordinary server response.
Error returned by the server code when a return_to is absent from a request.
An error indicating that the return_to URL is malformed.
This error is returned when the trust_root value is malformed.
The base class for all server request classes.
A request to verify the validity of a previous response.
A class implementing plaintext server sessions.
A class implementing DH-SHA1 server sessions.
A class implementing DH-SHA256 server sessions.
A request to associate with the server.
A request to confirm the identity of a user.
This class encapsulates the response to an OpenID server request.
A web-capable response object which you can use to generate a user-agent response.
Responsible for the signature of query data and the verification of OpenID signature values.
Encode an Auth_OpenID_ServerResponse to an Auth_OpenID_WebResponse.
An encoder which also takes care of signing fields when required.
Decode an incoming query into an Auth_OpenID_Request.
An error that indicates an encoding problem occurred.
An error that indicates that a response was already signed.
An error that indicates that the given return_to is not under the given trust_root.
I handle requests for an OpenID server.
Some types of requests (those which are not checkid requests) may be handed to my handleRequest method, and I will take care of it and return a response.
For your convenience, I also provide an interface to Auth_OpenID_Decoder::decode() and Auth_OpenID_SigningEncoder::encode() through my methods decodeRequest and encodeResponse.
All my state is encapsulated in an Auth_OpenID_OpenIDStore.
Example:
$oserver = new Auth_OpenID_Server(Auth_OpenID_FileStore($data_path), "http://example.com/op"); $request = $oserver->decodeRequest(); if (in_array($request->mode, array('checkid_immediate', 'checkid_setup'))) { if ($app->isAuthorized($request->identity, $request->trust_root)) { $response = $request->answer(true); } else if ($request->immediate) { $response = $request->answer(false); } else { $app->showDecidePage($request); return; } } else { $response = $oserver->handleRequest($request); }
$webresponse = $oserver->encode($response);
OpenID Server Request
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
Imports Object that holds the state of a request to the OpenID server
With accessor functions to get at the internal request data.
An SQLite store.
Require the base class file. An SQL store that uses SQLite as its backend.
SQL-backed OpenID stores.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
private private private This is the parent class for the SQL stores, which contains the logic common to all of the SQL stores.
The table names used are determined by the class variables associations_table_name and nonces_table_name. To change the name of the tables used, pass new table names into the constructor.
To create the tables with the proper schema, see the createTables method.
This class shouldn't be used directly. Use one of its subclasses instead, as those contain the code necessary to use a specific database. If you're an OpenID integrator and you'd like to create an SQL-driven store that wraps an application's database abstraction, be sure to create a subclass of Auth_OpenID_DatabaseConnection that calls the application's database abstraction calls. Then, pass an instance of your new database connection class to your SQLStore subclass constructor.
All methods other than the constructor and createTables should be considered implementation details.
Simple registration request and response parsing and object representation.
This module contains objects representing simple registration requests and responses that can be used with both OpenID relying parties and OpenID providers.
1. The relying party creates a request object and adds it to the Auth_OpenID_AuthRequest object before making the checkid request to the OpenID provider:
$sreg_req = Auth_OpenID_SRegRequest::build(array('email')); $auth_request->addExtension($sreg_req);
2. The OpenID provider extracts the simple registration request from the OpenID request using Auth_OpenID_SRegRequest::fromOpenIDRequest, gets the user's approval and data, creates an Auth_OpenID_SRegResponse object and adds it to the id_res response:
$sreg_req = Auth_OpenID_SRegRequest::fromOpenIDRequest( $checkid_request); // [ get the user's approval and data, informing the user that // the fields in sreg_response were requested ] $sreg_resp = Auth_OpenID_SRegResponse::extractResponse( $sreg_req, $user_data); $sreg_resp->toMessage($openid_response->fields);
3. The relying party uses Auth_OpenID_SRegResponse::fromSuccessResponse to extract the data from the OpenID response:
$sreg_resp = Auth_OpenID_SRegResponse::fromSuccessResponse( $success_response);
A base class for classes dealing with Simple Registration protocol messages.
An object to hold the state of a simple registration request.
required: A list of the required fields in this simple registration request
optional: A list of the optional fields in this simple registration request
Represents the data returned in a simple registration response inside of an OpenID C{id_res} response. This object will be created by the OpenID server, added to the C{id_res} response object, and then extracted from the C{id_res} message by the Consumer.
Functions for dealing with OpenID trust roots
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
URI normalization routines.
This is the PHP OpenID library by JanRain, Inc.
This module contains core utility functionality used by the library. See Consumer.php and Server.php for the consumer and server implementations.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
The OpenID utility function class.
private
This module contains the HTTP fetcher interface
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
This class is the interface for HTTP fetchers the Yadis library uses. This interface is only important if you need to write a new fetcher for some reason.
private
Yadis service manager to be used during yadis-driven authentication attempts.
The base session class used by the Auth_Yadis_Manager. This class wraps the default PHP session machinery and should be subclassed if your application doesn't use PHP sessioning.
A session helper class designed to translate between arrays and objects. Note that the class used must have a constructor that takes no parameters. This is not a general solution, but it works for dumb objects that just need to have attributes set. The idea is that you'll subclass this and override $this->check($data) -> bool to implement your own session data validation.
A concrete loader implementation for Auth_OpenID_ServiceEndpoints.
A concrete loader implementation for Auth_Yadis_Managers.
The Yadis service manager which stores state in a session and iterates over <Service> elements in a Yadis XRDS document and lets a caller attempt to use each one. This is used by the Yadis library internally.
State management for discovery.
High-level usage pattern is to call .getNextService(discover) in order to find the next available service for this user for this session. Once a request completes, call .cleanup() to clean up the session state.
Miscellaneous utility values and functions for OpenID and Yadis.
This module contains the CURL-based HTTP fetcher implementation.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
Interface import A paranoid Auth_Yadis_HTTPFetcher class which uses CURL for fetching.
This is the HTML pseudo-parser for the Yadis library.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
This class is responsible for scanning an HTML string to find META tags and their attributes. This is used by the Yadis discovery process. This class must be instantiated to be used.
This module contains the plain non-curl HTTP fetcher implementation.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
Interface import This class implements a plain, hand-built socket-based fetcher which will be used in the event that CURL is unavailable.
XML-parsing classes to wrap the domxml and DOM extensions for PHP 4 and 5, respectively.
The base class for wrappers for available PHP XML-parsing extensions. To work with this Yadis library, subclasses of this class MUST implement the API as defined in the remarks for this class. Subclasses of Auth_Yadis_XMLParser are used to wrap particular PHP XML extensions such as 'domxml'. These are used internally by the library depending on the availability of supported PHP XML extensions.
This concrete implementation of Auth_Yadis_XMLParser implements the appropriate API for the 'domxml' extension which is typically packaged with PHP 4. This class will be used whenever the 'domxml' extension is detected. See the Auth_Yadis_XMLParser class for details on this class's methods.
This concrete implementation of Auth_Yadis_XMLParser implements the appropriate API for the 'dom' extension which is typically packaged with PHP 5. This class will be used whenever the 'dom' extension is detected. See the Auth_Yadis_XMLParser class for details on this class's methods.
This module contains the XRDS parsing code.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
This class represents a <Service> element in an XRDS document. Objects of this type are returned by Auth_Yadis_XRDS::services() and Auth_Yadis_Yadis::services(). Each object corresponds directly to a <Service> element in the XRDS and supplies a getElements($name) method which you should use to inspect the element's contents. See Auth_Yadis_Yadis for more information on the role this class plays in Yadis discovery.
This class performs parsing of XRDS documents.
You should not instantiate this class directly; rather, call parseXRDS statically:
$xrds = Auth_Yadis_XRDS::parseXRDS($xml_string);
If the XRDS can be parsed and is valid, an instance of Auth_Yadis_XRDS will be returned. Otherwise, null will be returned. This class is used by the Auth_Yadis_Yadis::discover method.
Routines for XRI resolution.
The core PHP Yadis implementation.
PHP versions 4 and 5
LICENSE: See the COPYING file included in this distribution.
Contains the result of performing Yadis discovery on a URI.
This is the core of the PHP Yadis library. This is the only class a user needs to use to perform Yadis discovery. This class performs the discovery AND stores the result of the discovery.
First, require this library into your program source:
require_once "Auth/Yadis/Yadis.php";
To perform Yadis discovery, first call the "discover" method statically with a URI parameter:
$http_response = array(); $fetcher = Auth_Yadis_Yadis::getHTTPFetcher(); $yadis_object = Auth_Yadis_Yadis::discover($uri, $http_response, $fetcher);
If the discovery succeeds, $yadis_object will be an instance of Auth_Yadis_Yadis. If not, it will be null. The XRDS document found during discovery should have service descriptions, which can be accessed by calling
$service_list = $yadis_object->services();
which returns an array of objects which describe each service. These objects are instances of Auth_Yadis_Service. Each object describes exactly one whole Service element, complete with all of its Types and URIs (no expansion is performed). The common use case for using the service objects returned by services() is to write one or more filter functions and pass those to services():
$service_list = $yadis_object->services(
array("filterByURI",
"filterByExtension"));The filter functions (whose names appear in the array passed to services()) take the following form:
function myFilter(&$service) {
// Query $service object here. Return true if the service
// matches your query; false if not.
}This is an example of a filter which uses a regular expression to match the content of URI tags (note that the Auth_Yadis_Service class provides a getURIs() method which you should use instead of this contrived example):
function URIMatcher(&$service) {
foreach ($service->getElements('xrd:URI') as $uri) {
if (preg_match("/some_pattern/",
$service->parser->content($uri))) {
return true;
}
}
return false;
}The filter functions you pass will be called for each service object to determine which ones match the criteria your filters specify. The default behavior is that if a given service object matches ANY of the filters specified in the services() call, it will be returned. You can specify that a given service object will be returned ONLY if it matches ALL specified filters by changing the match mode of services():
$yadis_object->services(array("filter1", "filter2"),
SERVICES_YADIS_MATCH_ALL);See SERVICES_YADIS_MATCH_ALL and SERVICES_YADIS_MATCH_ANY.
Services described in an XRDS should have a library which you'll probably be using. Those libraries are responsible for defining filters that can be used with the "services()" call. If you need to write your own filter, see the documentation for Auth_Yadis_Service.
