Trackback Class
***************

The Trackback Class provides functions that enable you to send and
receive Trackback data.

If you are not familiar with Trackbacks you’ll find more information
here.

* Using the Trackback Class

  * Initializing the Class

  * Sending Trackbacks

  * Receiving Trackbacks

  * Your Ping URL

  * Creating a Trackback Table

  * Processing a Trackback

    * Notes:

* Class Reference


Using the Trackback Class
=========================


Initializing the Class
----------------------

Like most other classes in CodeIgniter, the Trackback class is
initialized in your controller using the "$this->load->library()"
method:

   $this->load->library('trackback');

Once loaded, the Trackback library object will be available using:

   $this->trackback


Sending Trackbacks
------------------

A Trackback can be sent from any of your controller functions using
code similar to this example:

   $this->load->library('trackback');

   $tb_data = array(
           'ping_url'  => 'http://example.com/trackback/456',
           'url'       => 'http://www.my-example.com/blog/entry/123',
           'title'     => 'The Title of My Entry',
           'excerpt'   => 'The entry content.',
           'blog_name' => 'My Blog Name',
           'charset'   => 'utf-8'
   );

   if ( ! $this->trackback->send($tb_data))
   {
           echo $this->trackback->display_errors();
   }
   else
   {
           echo 'Trackback was sent!';
   }

Description of array data:

* **ping_url** - The URL of the site you are sending the Trackback to.
  You can send Trackbacks to multiple URLs by separating each URL with
  a comma.

* **url** - The URL to YOUR site where the weblog entry can be seen.

* **title** - The title of your weblog entry.

* **excerpt** - The content of your weblog entry.

* **blog_name** - The name of your weblog.

* **charset** - The character encoding your weblog is written in. If
  omitted, UTF-8 will be used.

Note:

  The Trackback class will automatically send only the first 500
  characters of your entry. It will also strip all HTML.

The Trackback sending method returns TRUE/FALSE (boolean) on success
or failure. If it fails, you can retrieve the error message using:

   $this->trackback->display_errors();


Receiving Trackbacks
--------------------

Before you can receive Trackbacks you must create a weblog. If you
don’t have a blog yet there’s no point in continuing.

Receiving Trackbacks is a little more complex than sending them, only
because you will need a database table in which to store them, and you
will need to validate the incoming trackback data. You are encouraged
to implement a thorough validation process to guard against spam and
duplicate data. You may also want to limit the number of Trackbacks
you allow from a particular IP within a given span of time to further
curtail spam. The process of receiving a Trackback is quite simple;
the validation is what takes most of the effort.


Your Ping URL
-------------

In order to accept Trackbacks you must display a Trackback URL next to
each one of your weblog entries. This will be the URL that people will
use to send you Trackbacks (we will refer to this as your “Ping URL”).

Your Ping URL must point to a controller function where your Trackback
receiving code is located, and the URL must contain the ID number for
each particular entry, so that when the Trackback is received you’ll
be able to associate it with a particular entry.

For example, if your controller class is called Trackback, and the
receiving function is called receive, your Ping URLs will look
something like this:

   http://example.com/index.php/trackback/receive/entry_id

Where entry_id represents the individual ID number for each of your
entries.


Creating a Trackback Table
--------------------------

Before you can receive Trackbacks you must create a table in which to
store them. Here is a basic prototype for such a table:

   CREATE TABLE trackbacks (
           tb_id int(10) unsigned NOT NULL auto_increment,
           entry_id int(10) unsigned NOT NULL default 0,
           url varchar(200) NOT NULL,
           title varchar(100) NOT NULL,
           excerpt text NOT NULL,
           blog_name varchar(100) NOT NULL,
           tb_date int(10) NOT NULL,
           ip_address varchar(45) NOT NULL,
           PRIMARY KEY `tb_id` (`tb_id`),
           KEY `entry_id` (`entry_id`)
   );

The Trackback specification only requires four pieces of information
to be sent in a Trackback (url, title, excerpt, blog_name), but to
make the data more useful we’ve added a few more fields in the above
table schema (date, IP address, etc.).


Processing a Trackback
----------------------

Here is an example showing how you will receive and process a
Trackback. The following code is intended for use within the
controller function where you expect to receive Trackbacks.:

   $this->load->library('trackback');
   $this->load->database();

   if ($this->uri->segment(3) == FALSE)
   {
           $this->trackback->send_error('Unable to determine the entry ID');
   }

   if ( ! $this->trackback->receive())
   {
           $this->trackback->send_error('The Trackback did not contain valid data');
   }

   $data = array(
           'tb_id'      => '',
           'entry_id'   => $this->uri->segment(3),
           'url'        => $this->trackback->data('url'),
           'title'      => $this->trackback->data('title'),
           'excerpt'    => $this->trackback->data('excerpt'),
           'blog_name'  => $this->trackback->data('blog_name'),
           'tb_date'    => time(),
           'ip_address' => $this->input->ip_address()
   );

   $sql = $this->db->insert_string('trackbacks', $data);
   $this->db->query($sql);

   $this->trackback->send_success();


Notes:
~~~~~~

The entry ID number is expected in the third segment of your URL. This
is based on the URI example we gave earlier:

   http://example.com/index.php/trackback/receive/entry_id

Notice the entry_id is in the third URI segment, which you can
retrieve using:

   $this->uri->segment(3);

In our Trackback receiving code above, if the third segment is
missing, we will issue an error. Without a valid entry ID, there’s no
reason to continue.

The $this->trackback->receive() function is simply a validation
function that looks at the incoming data and makes sure it contains
the four pieces of data that are required (url, title, excerpt,
blog_name). It returns TRUE on success and FALSE on failure. If it
fails you will issue an error message.

The incoming Trackback data can be retrieved using this function:

   $this->trackback->data('item')

Where item represents one of these four pieces of info: url, title,
excerpt, or blog_name

If the Trackback data is successfully received, you will issue a
success message using:

   $this->trackback->send_success();

Note:

  The above code contains no data validation, which you are encouraged
  to add.


Class Reference
===============

class CI_Trackback

   $data = array('url' => '', 'title' => '', 'excerpt' => '', 'blog_name' => '', 'charset' => '')

      Trackback data array.

   $convert_ascii = TRUE

      Whether to convert high ASCII and MS Word characters to HTML
      entities.

   send($tb_data)

      Parameters:
         * **$tb_data** ("array") – Trackback data

      Returns:
         TRUE on success, FALSE on failure

      Return type:
         "bool"

      Send trackback.

   receive()

      Returns:
         TRUE on success, FALSE on failure

      Return type:
         "bool"

      This method simply validates the incoming TB data, returning
      TRUE on success and FALSE on failure. If the data is valid it is
      set to the "$this->data" array so that it can be inserted into a
      database.

   send_error([$message = 'Incomplete information'])

      Parameters:
         * **$message** ("string") – Error message

      Return type:
         "void"

      Responses to a trackback request with an error message.

      Note:

        This method will terminate script execution.

   send_success()

      Return type:
         "void"

      Responses to a trackback request with a success message.

      Note:

        This method will terminate script execution.

   data($item)

      Parameters:
         * **$item** ("string") – Data key

      Returns:
         Data value or empty string if not found

      Return type:
         "string"

      Returns a single item from the response data array.

   process($url, $data)

      Parameters:
         * **$url** ("string") – Target url

         * **$data** ("string") – Raw POST data

      Returns:
         TRUE on success, FALSE on failure

      Return type:
         "bool"

      Opens a socket connection and passes the data to the server,
      returning TRUE on success and FALSE on failure.

   extract_urls($urls)

      Parameters:
         * **$urls** ("string") – Comma-separated URL list

      Returns:
         Array of URLs

      Return type:
         "array"

      This method lets multiple trackbacks to be sent. It takes a
      string of URLs (separated by comma or space) and puts each URL
      into an array.

   validate_url(&$url)

      Parameters:
         * **$url** ("string") – Trackback URL

      Return type:
         "void"

      Simply adds the *http://* prefix it it’s not already present in
      the URL.

   get_id($url)

      Parameters:
         * **$url** ("string") – Trackback URL

      Returns:
         URL ID or FALSE on failure

      Return type:
         "string"

      Find and return a trackback URL’s ID or FALSE on failure.

   convert_xml($str)

      Parameters:
         * **$str** ("string") – Input string

      Returns:
         Converted string

      Return type:
         "string"

      Converts reserved XML characters to entities.

   limit_characters($str[, $n = 500[, $end_char = '…']])

      Parameters:
         * **$str** ("string") – Input string

         * **$n** ("int") – Max characters number

         * **$end_char** ("string") – Character to put at end of
           string

      Returns:
         Shortened string

      Return type:
         "string"

      Limits the string based on the character count. Will preserve
      complete words.

   convert_ascii($str)

      Parameters:
         * **$str** ("string") – Input string

      Returns:
         Converted string

      Return type:
         "string"

      Converts high ASCII text and MS Word special characterss to HTML
      entities.

   set_error($msg)

      Parameters:
         * **$msg** ("string") – Error message

      Return type:
         "void"

      Set an log an error message.

   display_errors([$open = '
'[, $close = '
']])

      Parameters:
         * **$open** ("string") – Open tag

         * **$close** ("string") – Close tag

      Returns:
         HTML formatted error messages

      Return type:
         "string"

      Returns error messages formatted in HTML or an empty string if
      there are no errors.
