Talk To Me!

Build a comments system for your Web site with PHP.

The Online Face Of Democracy

I’ve always thought that the nice thing about sites like Slashdot [http://www.slashdot.com], PHPBuilder [http://www.phpbuilder.com] and Devshed [http://www.devshed.com] is that they allow users to comment on the articles and news items posted on the site. By adding this much-needed element of interactivity (not to mention striking a blow for free speech), content-rich portals build a sense of community among users, offer an immediate and public forum for user feedback…and also provide a fair amount of entertainment in the eccentric and unpredictable postings that sometimes appear.

Over the next few pages, I’m going to take you through the process of adding this kind of interactivity to your own Web site. I’m going to base this loosely on a project we did recently for one of our customers, and so this case study will make some assumptions as to the existing architecture of the Web site in question. However, you should have little trouble adapting the principles below to add the same kind of capabilities to your own pages.

Let’s get started!

The Job

Since we were called upon to graft this interactive comments system on to an existing Web site, we had to take into account the underlying architecture, as well as the customer’s requirements and constraints, before beginning work on the applications. The first was a matter of a few hours; the second, a few weeks (if you’re a developer, I’m sure you know exactly what I mean)

The underlying architecture of the Web site in question is actually pretty simple. The site is divided into a number of different top-level categories, like entertainment, news, politics, travel and the like. Each article on the site is represented by a record in a table; this table contains the title of each article, an abstract and the complete content of the article.

Each article (record) is identified by a category number and an article number - this combination is unique to each article, and makes it possible to immediately display a specific article. Article numbers are not unique across categories - for example, you might have an article numbered 56 in category 3, and a similar article number in category 8 - but the combination of article and category number is unique across the site.

A single PHP script takes care of displaying the articles on the site. This script requires the category number and the article number; it then uses this information to connect to the database, retrieve the article identified by those two parameters, and display it appropriately.

Our understanding of the customer’s requirements boiled down to the following tasks:

  1. Create a PHP script to accept comments from the user, and store these comments in a table.

  2. Create a PHP script to display comments for a specific article. An additional requirement here was that comments were to be displayed in a “threaded” fashion, as on USENET bulletin boards.

  3. Add appropriate links to read and post comments to the existing user interface.

If you’re looking at this from the point of view of your own Web site, the above tasks encompass about 90% of the functionality in any comments system - and they’re not even very difficult to accomplish.

Building The Foundation

This is a good time for you to download the source code, so that you can refer to it throughout this tutorial (you will need a Web server capable of running PHP and a mySQL database in order to run the application).

Download: comments.zip

The first order of business is to design a table that will hold the comments entered by the user. After much thought, discussion and stale pizza, here is the structure we finally decided on.

#
# Table structure for table 'comments'
# comments.sql in the source archive
#

DROP TABLE IF EXISTS comments;
CREATE TABLE comments (
   id int(11) NOT NULL auto_increment,
   article int(11) DEFAULT '0' NOT NULL,
   section int(11) DEFAULT '0' NOT NULL,
   username varchar(100) NOT NULL,
   email varchar(255),
   timestamp timestamp(14),
   subject varchar(255) NOT NULL,
   post text NOT NULL,
   replytopost int(11) DEFAULT '0' NOT NULL,
   PRIMARY KEY (id)
);

#
# description of fields:
#
# id - unique numeric identifier for each comment in table
# article - comment belongs to this article
# section - article belongs to this section
# username - name of user posting comment
# email - email address of user posting comment
# timestamp - time of post (automatically generated)
# subject - subject of post
# post - body of post
# replytopost - if replying to existing post, numeric identifier of that post (required for threading)
#

We decided that each post would display the author’s name, email address and date/time on which it was posted. Our original table did not include a field for the subject; this was added in order to make it easier for readers to quickly divine the nature of the post, and thereby decide whether or not it was worth reviewing.

In this structure, each post is identified by a number. This number, combined with the “replytopost” attribute, comes in very useful when constructing a threaded list of posts (as you’ll see a little further down). The “replytopost” attribute identifies the post one level up in the discussion “tree”, and thereby makes is easier to relate one post to another when constructing the threaded tree structure. A “replytopost” value of 0 indicates that there are no posts above this one in the tree…in other words, that this is a new “branch” of the discussion tree.

Mole In A Hole

With the table designed as per requirements, it’s time to actually start writing some code. The first thing to do is to add links to the main article display page, allowing users to read and post comments.

Let’s take a look at a stripped-down version of this page, called “start.php”.

<?php
// important information to identify this article
$section = 3;
$article = 99;
?>
<html>
<head>
</head>

<body>

<!-- snip! -->

<font face="Verdana, Arial" size="4" color="#66CC00">
<!-- getArticleTitle($section,$article) -->
Mole In A Hole
</font>
<p>
<font face="Verdana, Arial" size="2" color="Black">
<!-- getArticleAbstract($section,$article) -->
Some things just don't change - at thirty, Adrian Mole is still the whining, unfulfilled loser we first encountered at age 13. He's still writing to the BBC, he's still madly in love with Pandora, now a high-profile politician in Blair's New Britannia, his family is still as dysfunctional as ever. More in our exclusive review of the new Sue Townsend novel.
</font>

<!-- snip! -->

</body>
</html>

Under normal circumstances, this page would receive the section and article numbers via the URL GET method, and then display the appropriate content. For example, the article entitled “Where Are We Going?” in the politics section (7) could be obtained at the URL

start.php?section=7&article=32

while a feature on Moscow in December could be obtained from the travel section (11) at

start.php?section=11&article=7

For explanatory purposes, I’ll assume that the article number is 99 and the section number is 3 (entertainment, for those of you who care), and so I’ve hard-coded these values at the top of the page. I’ve also replaced a couple of function calls with their return values, again to make it easier to see what’s going on.

Now, let’s add those links.

<?php
// start.php

// important information to identify this article
$section = 3;
$article = 99;
?>
<html>
<head>
</head>

<body>

<!-- snip! -->
<font face="Verdana, Arial" size="4" color="#66CC00">
<!-- getArticleTitle($section,$article) -->
Mole In A Hole
</font>
<p>
<font face="Verdana, Arial" size="2" color="Black">
<!-- getArticleAbstract($section,$article) -->
Some things just don't change - at thirty, Adrian Mole is still the whining, unfulfilled loser we first encountered at age 13. He's still writing to the BBC, he's still madly in love with Pandora, now a high-profile politician in Blair's New Britannia, his family is still as dysfunctional as ever. More in our exclusive review of the new Sue Townsend novel.
<p>
<!-- snip! -->
<a href="post.php?section=<?php echo $section; ?>&article=<?php echo $article; ?>">Comment</a> on this article, or
<a href="list.php?section=<?php echo $section; ?>&article=<?php echo $article; ?>">view other people's comments</a>
</font>

</body>
</html>

As you can see, both “post.php” and “list.php” will now receive the section and article numbers via the URL GET method.

Here’s what the page looks like:

Shameless plug - you can find a copy of the book review above at http://www.melonfire.com/community/columns/colophon/article.php?id=61, together with lots of other cool stuff. Knock yourself out!

Speak Now, Or Forever Hold Your Peace

Next, I’m going to construct a form which will ask for some basic user information, and allow the user to enter a comment on the article. Once that form is submitted, a PHP script will process the information entered into it and store the result in the database via an INSERT operation.

For purposes of convenience, both the initial form and the result page have been embedded in the same PHP script, “post.php”, with the $submit variable used to decide which page is displayed. Here’s the initial form.

<?php
// post.php
if($submit)
{
// form has been submitted
// form processing code
}
else
{
// display initial form
?>

<form action="<?php echo $PHP_SELF; ?>" method="post">
<input type="hidden" name="replytopost" value="<?php echo $replytopost; ?>">
<input type="hidden" name="section" value="<?php echo $section; ?>">
<input type="hidden" name="article" value="<?php echo $article; ?>">

<table border="0" cellspacing="5" cellpadding="0">
<tr>
<td colspan=2>
<font face="Verdana, Arial" size="2" color="Black"><b>Your comment:</b></font><p>
</td>
</tr>
<tr>
<td><font face="Verdana, Arial" size="2" color="Black">Name</font></td>
<td><input type="text" name="username" size="25"></td>
</tr>
<tr>
<td><font face="Verdana, Arial" size="2" color="Black">Email address</font></td>
<td><input type="text" name="email" size="25"></td>
</tr>

<tr>
<td><font face="Verdana, Arial" size="2" color="Black">Subject</font></td>
<td><input type="text" name="subject" size="25"></td>
</tr>
<tr>
<td><font face="Verdana, Arial" size="2" color="Black">Comment</font></td>
<td><textarea name="post" rows="5"></textarea></td>
</tr>
<tr>
<td colspan=2 align=center><input type="submit" name="submit" value="Add Comment"></td>
</tr>
</table>
</form>

Here’s what it looks like:

Once the form is submitted, the same script is called upon to process the data.

<?php
// post.php

if($submit)
{
// form has been submitted
// process form data
include("config.php");
$connection = mysql_connect($hostname, $user, $pass) or die ("Unable to connect!");

// indicates new comment, not reply
	if (!$replytopost)
		{
		$replytopost = 0;
		}

// correction for empty subject
// all form fields should be checked before executing the query
	if (!$subject)
		{
		$subject = "No subject";
		}

// correction for empty username
	if (!$username)
		{
		$username = "Anonymous";
		}

$query = "INSERT INTO $table (section, article, subject, post, username, email, replytopost, timestamp) VALUES ('$section', '$article', '$subject', '$post', '$username', '$email', '$replytopost', NOW())";

$result = mysql_db_query($database, $query, $connection) or die ("Error in query: $query . " . mysql_error());
?>
<font face="Verdana, Arial" size="2" color="Black">
Your comment has been posted. Click to <a href="list.php?section=<?php echo $section; ?>&article=<?php echo $article; ?>">read more comments</a>.
<?php
}
else
{
// display initial form
}
?>

This script simply checks the form variables, corrects empty ones, and then INSERTs the data into the database. If this is a “new” comment (as opposed to a “reply”), the $replytopost variable is set to 0.

In case you’re wondering what the include() is all about at the top of the script, the file “config.php” simply stores some basic parameters required to connect to the database. Here it is.

<?php
// database parameters
// alter this as per your configuration
$database="db39492";
$table = "comments";
$user = "root";
$pass = "gsfd3k6";
$hostname = "localhost";
?>

Once the data has been stored in the database, a success code is returned, and a link offered to read other comments that may have been posted. Let’s take a look at that next.

Of Trees And Branches

The script “list.php” is designed to display a threaded list of all the comments posted for a specific article - it accomplishes this via the buildTree() function.

<?php
// list.php
include("config.php");
include("common.php");
$connection = mysql_connect($hostname, $user, $pass) or die ("Unable to connect!");
?>
<html>
<head>
</head>
<body>
<hr>

<?php
// start building a comment tree
buildTree(0,$article, $section);
?>

<hr>
</body>
</html>

The buildTree() function is the guts of this application. It is a recursive function that performs one query after another to create a threaded list of posts, starting from a specific branch of the tree and working its way progressively through all sub-branches. Take a look.

<?php
//this is the recursive function which is called to render the inner children of every comment
function buildTree($id, $article, $section)
{
// get some variables
global $connection;
global $database;
global $table;

// select all comments for that article and section
// if an id is present, select comments which are branches on that comment "tree"
$query = "SELECT id, subject, timestamp, username FROM $table where article = '$article' AND section = '$section' AND replytopost = '$id'";

$result = mysql_db_query($database, $query, $connection) or die ("Could not execute query: $query. " . mysql_error());

	// if at tree root and no comments available, display error
	if(mysql_num_rows($result) <= 0 && $id == 0)
	{
		echo "<font face=Verdana size=2 color=Black><b>No comments available</b></font>";
	}
	else
	{
		// display records
		while(list($ID, $SUBJECT, $TIMESTAMP, $USERNAME) = mysql_fetch_row($result))
		{
			echo "<ul>\n";
			echo "<li><a href=details.php?id=$ID&section=$section&article=$article><font face=Verdana size=2 color=Black><b>$SUBJECT</b></a>&nbsp;</li>\n";

			// this part is what causes the recursion - it exits the function
			// when there are no more records(children) to render
			buildTree($ID,$article, $section);
		echo "</ul>\n ";
		}
	}
}
?>

Let’s dissect this a little.

First, this function assumes that a connection to the database has been created - if you take a look, you’ll see that that is one of the first things “list.php” does. It also needs some variables - the name of the database and table to perform queries on, the level at which to start building the tree structure, and the article/section identifier (passed to it as parameters).

With all that information in place, buildTree() performs a SELECT query and obtains a list of “level 0” posts; it then prints these in a list. For each record thus returned, buildTree() then calls itself recursively with that record number, connects to the database again, and displays a list of all “level 1” posts. This process continues until the end of the tree is reached. The HTML list construct is used to ensure that different levels are indented appropriately. If no comments are found at level 0, a message indicating this is displayed.

As you might imagine, this process can certainly test the strength of a database server, especially if there are a large number of levels. That’s why you should ensure that your system has enough processing power to handle this kind of multi-level query.

Each item in the list finally displayed is linked to the “details.php” page, which displays the complete content of the comment. Here’s what it looks like:

Closing The Loop

The final piece of the puzzle is the script “details.php”, which uses the values passed to it on the URL (article, section and comment identifiers) to query the database and return a single page containing the author’s name, the time at which the comment was posted, and the body of the comment. In case the author has included an email address, it is placed within a mailto: hyperlink and printed as well.

<html>
<head>
<basefont face="Verdana, Arial">
</head>
<body>
<font face="Verdana, Arial" size="4" color="#66CC00">
Mole In A Hole
</font>

<p>

<font face="Verdana, Arial" size="2" color="Black">
Some things just don't change - at thirty, Adrian Mole is still the whining, unfulfilled loser we first encountered at age 13. He's still writing to the BBC, he's still madly in love with Pandora, now a high-profile politician in Blair's New Britannia, his family is still as dysfunctional as ever. More in our exclusive review of the new Sue Townsend novel.
<p>
<a href="post.php?section=<?php echo $section; ?>&article=<?php echo $article; ?>">Comment</a> on this article.
<p>
<hr>

<?php
include("config.php");
include("common.php");

// connect and get this post
$connection = mysql_connect($hostname, $user, $pass) or die ("Unable to connect!");
$query = "SELECT username, email, subject, post, timestamp from $table WHERE id = $id";
$result = mysql_db_query($database, $query, $connection) or die ("Error in query: $query. " . mysql_error());

// display post content
list($username, $email, $subject, $post, $timestamp) = mysql_fetch_row($result);

// if email address available, place it in a mailto:
if ($email) { $email = "&lt;<a href=mailto:" . $email . ">" . $email . "</a>&gt"; }

echo "<font face=verdana size=2 color=black>Posted by <b>$username</b> $email on " . formatDate($timestamp) . "<br>";
echo "<b>Subject</b>: $subject<br>";
echo "<b>Comment:</b> " . nl2br($post) . "</font><p>";

?>
<hr>

<a href="post.php?replytopost=<?php echo $id; ?>&section=<?php echo $section; ?>&article=<?php echo $article; ?>">Reply</a> to this post or
<a href="list.php?section=<?php echo $section; ?>&article=<?php echo $article; ?>">read more comments</a>

</font>
</body>
</html>

Here’s what it looks like:

`

Pay special attention to the “reply” link at the bottom of the post - in case a reader wishes to reply to this specific post, the $replytopost variable holds the name of the post that is being replied to. This $replytopost variable is then transferred to “post.php” as an additional parameter and stored in the database, thereby completing the loop required to generate the discussion tree.

The formatDate() function is used to convert the 14-digit mySQL timestamp into something a little more readable.

// format the date correctly
function formatDate($val)
{
// split up the timestamp
$year=substr($val,0,4);
$month=substr($val,4,2);
$day=substr($val,6,2);
$hh=substr($val,8,2);
$mm=substr($val,10,2);
// convert it into a standard timestamp and format it
$date = date("d M Y H:i", mktime($hh, $mm, 0, $month, $day, $year));
return $date;
}

The Last Word

There are a couple of other things that can be added to complete this application. First, since all this work will come to naught if the article and section numbers are not transmitted correctly, you can build in a rudimentary error check by validating the presence of these two variables before performing any database operation. In case these variables are not present, simply redirect the user to an error page.

<?php
// redirect if missing important parameters
// place at the top of every page
if (!$article || !$section) { header("Location: error.php"); }
?>

In the interests of consistency, you might also like to connect related posts to one another by including the string “Re: “ in the subject line of replies, as on USENET. This is a relatively simple operation to accomplish - simply add this refinement to “post.php”.

<form action="<?php echo $PHP_SELF; ?>" method="post">
<input type="hidden" name="replytopost" value="<?php echo $replytopost; ?>">
<input type="hidden" name="section" value="<?php echo $section; ?>">
<input type="hidden" name="article" value="<?php echo $article; ?>">

<table border="0" cellspacing="5" cellpadding="0">
<tr>
<td colspan=2>
<font face="Verdana, Arial" size="2" color="Black"><b>Your comment:</b></font><p>
</td>
</tr>
<tr>
<td><font face="Verdana, Arial" size="2" color="Black">Name</font></td>
<td><input type="text" name="username" size="25"></td>
</tr>
<tr>
<td><font face="Verdana, Arial" size="2" color="Black">Email address</font></td>
<td><input type="text" name="email" size="25"></td>
</tr>
<?php
// if this is a reply to an existing post
if ($replytopost)
{
	// connect to database and pre-fill the subject field
	include("config.php");
	$connection = mysql_connect($hostname, $user, $pass) or die ("Unable to connect!");

	$query = "SELECT subject FROM $table WHERE id='$replytopost'";

	$result = mysql_db_query($database, $query, $connection) or die ("Error in query: $query . " . mysql_error());

	list($subject) = mysql_fetch_row($result);
	// fix the subject line if necessary
	$substring = substr($subject,0, 3);
	if ($substring != "Re:")
		{
		$subject = "Re: " . $subject;
		}

}
?>
<tr>
<td><font face="Verdana, Arial" size="2" color="Black">Subject</font></td>
<td><input type="text" name="subject" size="25" value="<?php if ($subject) { echo $subject; } ?>"></td>
</tr>
<tr>
<td><font face="Verdana, Arial" size="2" color="Black">Comment</font></td>
<td><textarea name="post" rows="5"></textarea></td>
</tr>
<tr>
<td colspan=2 align=center><input type="submit" name="submit" value="Add Comment"></td>
</tr>
</table>
</form>

In the case of replies (indicated by the presence of the $replytopost variable), the subject field in the form is pre-filled with the subject of the parent post (obtained by querying the database), and the string “Re: “ is prefixed to it. The user can, of course, replace this suggested subject line with anything else (s)he chooses.

Here’s what it looks like:

Finally, it should be said that this system, as described above, is by no means perfect. For example, the passing of parameters via the URL GET method is an inherent vulnerability, allowing experienced users to alter the parameters and the subsequent attributes of the record in the database. A possible solution to this is to store the relevant numbers in session variables, which are inaccessible to the user, and thereby prevent mischief.

It should also be noted that the architecture on which this application is premised is by no means optimal - a few obvious flaws present themselves, the primary one being the odd duality of the article and section number combination. However, when performing development on an existing, active Web site with a pre-defined database architecture (as we were), and given the constraints inherent in such a situation, it’s difficult to redesign a system from scratch, and often, the only practical (and cost-effective) option is to simply build on existing plumbing rather than going back to square one.

Either way, I hope this case study has given you some insight into how many Web sites build their online discussion forums, and perhaps also sparked some ideas on how you can apply this application to your own development activities. See you soon!

Note: All examples in this article have been tested on Linux/i586 with Apache 1.3.14 and PHP 4.0. Examples are illustrative only, and are not meant for a production environment. YMMV!

This article was first published on 08 Mar 2001.