edit

Pingback

The Pingback class is a pingback 1.0 protocol (client and server) implementation.

Namespace: Web
File location: lib/web/pingback.php

---

Requirements

The Pingback class needs the PHP XML-RPC extension. The Pingback class won't work without it.

You can easily check for its availability on your server this way:

$isPingbackAvailable = extension_loaded('xmlrpc');  // returns TRUE or FALSE

Instantiation

Return class instance

$pingback = Web\Pingback::instance();

The Pingback class uses the Prefab factory wrapper, so you can grab the same instance of that class at any point of your code.

Methods

inspect

Load local page contents, parse HTML anchor tags, find permalinks, and send XML-RPC calls to corresponding pingback servers

NULL inspect ( string $source )

This function performs a web request to load the local page contents given by the $source URL. Then the retrieved response is parsed, looking for HTML anchor tags. For every permalink found (<link rel="pingback" /> typically) inside the page, a XML-RPC call is send to the corresponding pingback server (METHOD POST). (Every XML-RPC call is logged. See function log() below to retrieve transactions history.)

Example:

$pingback->inspect($source);

listen

Receive ping, check if local page is pingback-enabled, verify source contents, and return XML-RPC response

string listen ( callback $func [ , string $path = NULL ] )

This function allows you to setup a XML-RPC listener. You need to define a F3 route and bind it to this function.

The function basically 'listen', once bound to a F3 route, to receive a ping, checks then if the local page is pingback-enabled, verifies the source contents, and for each link found in the source contents, use a given $func callback function to return a XML-RPC response.

The $func parameter is the name of your callback function to use to handle the request/ping. It will be called like this:

call_user_func_array($func, array($source,$req['body']));

with $source being the URL of the source, and $req['body'] the body part returned

If $path is not provided, the value of the BASE system variable is used.

On success, this function will die returning the XML response content as per the xmlrpc_encode_request php function:

// Success
die(xmlrpc_encode_request(NULL,$source,$options));

On error, this function will die returning the XML response consisting of one of the following error code as follow:

die(xmlrpc_encode_request(NULL,0x11,$options));  // No link to local page found in request body

die(xmlrpc_encode_request(NULL,0x10,$options));  // Source failure: web request failed or received doc malformed

die(xmlrpc_encode_request(NULL,0x21,$options));  // Local page doesn't exist or is not pingback-enabled

die(xmlrpc_encode_request(NULL,0x31,$options));  // Access denied: request method is not 'pingback.ping' or request malformed

Now, let's setup a basic example of a XML-RPC ping handler:

We need a route, a listening function to bind to, and a callback function:

// the callback function called by the listen() function. Takes 2 parameters
function pingCallBackHandler($sourceURL, $reqBody) {
	$logger = new Log('pings.log');
	$logger->write('Incoming ping from '.$sourceURL);
	// any processing on the $reqBody
	$logger->write('Request body length is '.
			\UTF::instance()->strlen($reqBody));
}

// a route as an example, e.g.
$f3->route('GET /listener','PingListener');

// the function to bind to the listener:
function PingListener($f3, $params) {

	$pingback = new \Web\Pingback;
	// bind it with our custom callback function
	$pingback->listen('pingCallBackHandler');
	return;
}

log

Return transaction history

string log ( )

This function returns the transaction history as logged by the inspect() function. The transaction history consists of a list of the permalinks URLs found in every inspected page, and this for every request response.

Example:

echo $pingback->log();

// Outputs:
Mon, 06 Jan 2014 10:23:00 +0100 /comments-feed?page=pingback/cf [permalink:/pingback]
   /pingback2?page=pingback/client

Mon, 06 Jan 2014 10:23:01 +0100 /rss2-feed?page=pingback/rss2 [permalink:/rss2-ping]
 /pingback2?page=rss2-ping/client
 

__construct

Instantiate class

object __construct ( )

The constructor allows you to instantiate the class.

Example:

$pingback = new Pingback (  )

Notice: As a convenience, this constructor calls libxml_use_internal_errors(TRUE) to suppress errors caused by invalid HTML structures.

enabled

Return TRUE if URL points to a pingback-enabled resource

protected bool enabled ( $url )

This function returns TRUE if the given URL points to a pingback-enabled resource.

This is a protected function used internally by inspect() and listen() to make sure a given URL points to a pingback-enabled resource, i.e. it looks for a valid pingback header and scan the page to make sure it contains pingback link tag(s).