+ +
+

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

+

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 = '<p>'[, $close = '</p>']])
+
+++ + + + + + + + +
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.

+
+ +
+ +
+
+ + +