Level: Intermediate

Vikram Vaswani, Founder, Melonfire

25 Mar 2008

Trackbacks play an important role in allowing blog readers to find and follow links to useful related content. The PEAR Services_Trackback package lets developers manually generate these trackbacks through a well-defined PHP API that takes care of creating trackback requests and parsing XML responses.

Introduction

One of the nice things about the blogosphere is how highly-networked and rapidly-evolving a community it is. By posting useful content and linking it to relevant material posted by other bloggers, an individual blogger can rapidly make his presence felt in the community and even build a fan base in a fraction of the time it would take in the real world.

Frequently used acronyms API - application programming interface PHP - PHP: Hypertext Preprocessor XML - Extensible Markup Language

Among the various tools used by bloggers to link posts together is the trackback, which provides a mechanism for one blogger to tell another of a related post or resource through a backlink. Trackbacks play an important role in strengthening the inter-connections between blogs, and also provide a convenient (and automatic) way for blog readers to find out about useful, related content.

If you already have a blog, chances are that you can use the built-in features of your blog to create trackbacks to content on other blogs. But what if you don't have a blog, but still want to create trackbacks between your Web posts and other blogs? Well, if you use PHP, you can benefit from the Services_Trackback package, which provides a generic mechanism to manually create and send trackbacks.

Back to top

Installation

The Services_Trackback package is maintained by Tobias Schlitt, and released to the PHP community under a PHP license. It is freely available from PEAR, the PHP Extension and Application Repository, and the easiest way to install it is with the automated PEAR installer, which should have been included by default with your PHP build. To install it, simply issue the following command at your shell prompt:

shell> pear install Services_Trackback

The PEAR installer will now connect to the PEAR package server, download the package, and install it to the appropriate location on your system. This tip uses Services_Trackback V0.6.1 (beta).

To install the package by hand, visit its home page, download the source code archive, and manually uncompress the files to the desired location. Note that this manual installation process presupposes some knowledge of PEAR's package organization structure. You'll find a link to the package's home page in the Resources of this tip.

Back to top

Overview and Basic Usage

Before you dive into Services_Trackback, a few words about how trackbacks work are in order. The original Trackback specification was developed by SixApart, and it specifies that a trackback request is initiated by sending a POST request over HTTP to a specified trackback URL. This trackback URL is the URL defined by the source blog to receive trackback requests for a specific post.

This POST request contains various bits of information to make the trackback more useful:

• The title and name of the Web page initiating the trackback
• A relevant excerpt from the page content
• The URL of the page that initiates the trackback

Of these pieces of information, only the URL of the page that initiates the trackback is mandatory; however, to create trackbacks that are relevant and useful, you should always include meaningful content for the other fields as well.

Listing 1 has an example of one such POST request, which creates a trackback to the original post at http://www.originating.blog.com/the/original/post:

                                
POST /the/original/post/trackback
Content-Type: application/x-www-form-urlencoded
title=Trackback+Test&url= http%3A%2F%2Fmy.blog.domain%2Fsome%2Fpost%2F
&excerpt=This+is+what+I+said+about+your+post...&blog_name=My+Blog
        

Now, when the destination server receives this trackback request, the server generates one of two responses, both formatted in XML. If the trackback request is in order, does not appear to be spam and the host initiating the trackback does not appear on a blacklist, the server will typically accept and create the trackback link, responding with the success message in Listing 2:

                                
<?xml version="1.0" encoding="utf-8"?>
<response>
    <error>0</error>
</response>
        

If, on the other hand, the trackback fails, an error message like Listing 3 is generated:

                                
<?xml version="1.0" encoding="utf-8"?>
<response>
    <error>11</error>
    <message>Database error, could not save trackback</message>
 </response
        

Fortunately, Services_Trackback does all the work to generate the POST request and decode the response for you. Listing 4 demonstrates typical usage of this package:

                                
<?php
$trackbackData = array(
    'title'     => 'Trackback Test',
    'excerpt'   => 'This is what I said about your post...',
    'url'       => 'http://my.blog.domain/some/post/',
    'blog_name' => 'My Blog',
    'trackback_url' => 'http://www.originating.blog.com/the/original/post/trackback'
);

// include class
include "Services/Trackback.php";

// initialize new instance 
$trackback = new Services_Trackback();

// set object properties
foreach ($trackbackData as $k => $v) {
  $trackback->set($k, $v);
}

// send trackback
$ret = $trackback->send();
if (PEAR::isError($ret)) {
  echo "ERROR. Trackback failed because: " . $ret->getMessage();
} else {
  echo "Trackback successfully posted";
}
?>
        

Listing 4 uses Services_Trackback package in PHP to create and post a trackback to a blog post. It begins by reading the Services_Trackback class file and initializing an object instance of the Services_Trackback class. Next, the set() method of the class sets the various attributes of the trackback from an associative array: the trackback URL, the post title, post URL, blog name, and an excerpt from the post to quote in the trackback. Finally, the send() method of the object actually creates a POST packet containing the trackback request and transmit it to the trackback URL. If the return value from send() is not a PEAR Error, a success notification displays; if it is, the user sees an error notification containing the text of the XML error message.

Back to top

A Simple Application

It's quite easy to use the Services_Trackback package in an interactive manner. You create a Web form that allows users to post trackbacks to any blog that supports them. Listing 5 demonstrates:

                                
<html>
  <head></head>
  <body>
    <h2>Post a Trackback</h2>
    <?php if (!isset($_POST['submit'])) { ?>
    <form method="post" action="track3.php">
      Trackback URL:
      <br/>
      <input type="text" name="tb_url" size="30" />
      <p/>
      Blog name:
      <br/>
      <input type="text" name="my_blog_name"/>
      <p/>
      Post title:
      <br/>
      <input type="text" name="my_post_title"/>
      <p/>
      Post excerpt:
      <br/>
      <textarea name="my_post_excerpt" cols="30" rows="5"></textarea>
      <p/>
      Post URL:
      <br/>
      <input type="text" name="my_post_url" size="30" />
      <p/>
      <input type="submit" name="submit" />
    </form>
    <?php 
    } else {
      // encode POST data
      $title = $_POST['my_post_title'];  
      $excerpt = $_POST['my_post_excerpt'];  
      $url = $_POST['my_post_url'];  
      $tburl = $_POST['tb_url'];  
      $name = $_POST['my_blog_name'];  
      
      $trackbackData = array(
        'title'     => $title,
        'excerpt'   => $excerpt,
        'url'       => $url,
        'blog_name' => $name,
        'trackback_url' => $tburl
      );

      // include class
      include "Services/Trackback.php";
      
      // initialize new instance 
      $trackback = new Services_Trackback();
      
      // set object properties
      foreach ($trackbackData as $k => $v) {
        $trackback->set($k, $v);
      }
      
      // send trackback
      $ret = $trackback->send();
      if (PEAR::isError($ret)) {
        echo "ERROR. Trackback failed because: " . $ret->getMessage();
      } else {
        echo "Trackback successfully posted";
      }
    }    
    ?>
  </body>
</html>
        

Listing 5 generates a Web form that asks the user to input various attributes for a trackback: the trackback URL, post title and URL, blog name, and excerpt. This information is then submitted to a PHP script that initializes a new Services_Trackback object, and posts the trackback to the specified URL. The XML response is then decoded and a success or failure notification displayed.

Figure 1 illustrates what the Web form looks like:

As this example illustrates, the Services_Trackback package provides an easy way to manually create trackbacks to blog post requests. It's very useful when you need to generate a trackback to your content, but don't necessarily have a blog to do this with. Play with it some and see what you think!

Resources

• SixApart's trackback technical specification: Read about the Trackback framework for peer-to-peer communication and notifications between web sites.
  
  
• Trackbacks and trackback spam: Visit Wikipedia for more on the methods to request notification when somebody links to one of your documents and fraudulent pings from blogs that use trackbacks.
  
  
• Trackback Working Group: Stay updated with news on the trackback protocol.
  
  
• More PEAR packages related to PHP and XML development: Find other PEAR packages related to PHP and XML development.
  
  
• XML area on developerWorks: Get the resources you need to advance your skills in the XML arena.
  
  
• IBM XML certification: Find out how you can become an IBM-Certified Developer in XML and related technologies.
  
  
• XML technical library: See the developerWorks XML library for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks. For a complete list of XML tips to date, check out the tips summary page.
  
  
• developerWorks technical events and webcasts: Stay current with technology in these sessions.
  
  
• The technology bookstore: Browse for books on these and other technical topics.
  
  
• Podcasts: Tune in and catch up with IBM technical experts.

• The Services_Trackback package: Download this generic class for sending and receiving trackbacks.
  
  
• IBM trial software: Build your next development project with trial software available for download directly from developerWorks.
  
  

• Participate in the discussion forum.
  
  
• XML zone discussion forums: Participate in any of several XML-related discussions.
  
  
• developerWorks blogs: Check out these blogs and get involved in the developerWorks community.
  
  

About the author

		Vikram Vaswani is the founder and CEO of Melonfire, a consulting services firm with special expertise in open-source tools and technologies. He is also the author of the books PHP Programming Solutions and How to do Everything with PHP and MySQL.

Original link: http://www.ibm.com/developerwork...