How to add a custom CAPTCHA to phpBB2

Last Updated: 26 May, 2006

Overview

phpBB is "an open source, flat style, message board written in PHP." Because thousands of people use it with little or no modifications, it is a very popular target for spammers. They can use bots to automatically fill out the registration forms, including "clicking" on the activation link inside e-mails. A CAPTCHA is some sort of challenge that will (in theory) be easy for a human to solve, but hard for a computer to. Typically, they are implemented as a distorted word that the user must enter to complete the form.

sample CAPTCHA image

Disclaimer

The method that I will describe is very much a hack, but it is quite simple (despite looking long). I haven't packaged anything up in an installable mod. Consider this an exercise in how to make your own mods, as the principles here apply to any custom registration mod. If you prefer to use phpBB2's default CAPTCHA, just go to your control panel's General Admin, Configuration, and Enable Visual Confirmation and forget you saw this. :)

Some people may have difficulty reading a CAPTCHA image. If you think your audience will need assistance, it would be kind of you to supply an e-mail address for those who cannot read the image. There may, in fact, be legal reasons (depending on your line of business, etc.) why you have to supply a valid alternative. And last of all, I am not responsible for any damage done by following this tutorial.

Getting Started

You'll need several things:

• phpBB2 - This is tested and confirmed to work on version 2.0.19. If you pay attention to details, it should probably work on any 2.0.X version.
• freecap - Available at www.puremango.co.uk, freecap is a free PHP CAPTCHA script. We will be adding this to phpBB2's registration form.
• PHP 4/5 with GD enabled - Make sure GD is enabled. <?php phpinfo(); ?> should help you find out. This article will not discuss installing it.
• Admin Rights - You have to be able to edit the PHP files on the server.

Note that you will be editing three files. I highly recommend that you make a backup copy of these those files before you edit them. Once you are sure you will be able to get everything you need:

1. Get freecap and put it on the server. Either:
   
   
   • Use a Remote Shell
     • Telnet or SSH into your server
     • cd /my/path/to/phpBB2
     • wget http://www.puremango.co.uk/freecap1.4.1.zip (Note: be sure to check the website for the latest version.)
     • unzip -a freecap1.4.1.zip
     • rm freecap1.4.1.zip
     • mv freecap1.4.1 freecap
     
     
   • OR Use FTP Locally
     • Go to www.puremango.co.uk and download freecap.
     • Unzip it.
     • Rename the folder to freecap
     • FTP to your website, and upload the entire freecap folder to your phpBB2 folder. That is, make sure you have a /phpBB2/freecap folder with the files directly in that. (Obviously, if your phpBB2 is in a different folder, then substitute that in whenever appropriate.)
   
   
2. Configure freecap. You will need to edit the freecap.php file. You can either do it with a remote or local editor ... take your pick. So either way, open it up and edit it:
   
   
   • Configure the site_tag array to display your site's name. This is to prevent people being tricked into filling out your CAPTCHA for a spammer. I would suggest something like:

     $site_tags[0] = "";
     $site_tags[1] = "For Access to MYDOMAIN.COM";
     

     (Leaving the first [0] one empty will help prevent text from covering up the image.)
     
     
   • Pick a hash function:
     • PHP 4.3 or greater: $hash_func = "sha1";
     • Older versions: $hash_func = "crc32";
     You should see that line already in freecap.php. You may not need to change it.
     
     
   • Change max attempts: $max_attempts = 2000; This is just for testing purposes. After you are sure everything is working, you can set it back down to 20.
     
     
   • Change merge type (optional): $merge_type = 1; Personally, I find them hard to read when merged.
     
     
   • There are other things you can change if you want. Just read the file and follow its instructions. I would recommend making sure it works before you start changing a bunch of things.
   
   
3. Once you have made all those changes, save and upload freecap.php.
   
   
4. Open up mywebsite.com/phpBB2/freecap/freecap.php in a browser. You should see a CAPTCHA image. If you don't, make sure you have GD installed and running. Also, don't be concerned if you cannot read every word. There will be a link for generating a new image if the user cannot read it.
   
   
5. Now it's time to hack the phpBB2 template. If you are using the default skin, it will be in the folder: templates/subSilver. The name of the file is: profile_add_body.tpl. Edit it, and pick a spot where you want the CAPTCHA to go. I'd suggest under the password. Paste this HTML code:

   <tr>
   	<td class="row1"><span class="gen">CAPTCHA Image:</span><br />
   	<td class="row2">
   		<img id="freecap" src="/phpBB2/freecap/freecap.php" />
   		<div style="margin: 0.5em 0;">
   			<label style="font-size: 10px;" for="captcha">Word in Above Image:</label>
   			<input id="captcha" name="captcha" type="text" size="10" />
   		</div>
   		<div style="font-size: 10px;">
   			Cannot read the image? 
   			<a href="#" onclick="document.getElementById('freecap').src='/phpBB2/freecap/freecap.php?'+Math.random();">Click Here</a>
   			to generate a new one.
   		</div>
   	</td>
   </tr>
   

   Note: There are two places (underlined and in bold) in the above snippet where you may have to adjust the path to match yours. If you use a custom skin, you may have to modify the code slightly. But I'm sure you'll figure that out.
   
   
6. Save and upload the file. Go to your message board and check out the registration page. You should see the CAPTCHA. Clicking on the link should generate a new image. But it isn't activated yet.
   
   
7. Edit the phpBB2/includes/usercp_register.php file. (Remember to make a backup copy!) Around line 265, you'll see a block of code that says:

   	else if ( $mode == 'register' )
   	{
   		if ( empty($username) || empty($new_password) || empty($password_confirm) || empty($email) )
   		{
   			$error = TRUE;
   			$error_msg .= ( ( isset($error_msg) ) ? '<br />' : '' ) . $lang['Fields_empty'];
   		}
   	}
   

   You need to add some lines to it, just in front of that closing brace. That section should look like:

   	else if ( $mode == 'register' )
   	{
   		if ( empty($username) || empty($new_password) || empty($password_confirm) || empty($email) )
   		{
   			$error = TRUE;
   			$error_msg .= ( ( isset($error_msg) ) ? '<br />' : '' ) . $lang['Fields_empty'];
   		}
   	
   		session_start();
   		if (!isset($_POST['captcha']) || !isset($_SESSION['freecap_word_hash']) || $_SESSION['hash_func']($_POST['captcha']) != $_SESSION['freecap_word_hash'])
   		{
   			$error = TRUE;
   			$error_msg .= ( ( isset($error_msg) ) ? '<br />' : '' ) . "The word you entered did not match the image.";
   		}
   		unset($_SESSION['freecap_word_hash']);
   
   	}
   

   Note that you are only adding those seven lines in bold!
   
   
8. Test it out. Just enter a word and hit submit. It should give you an error if you type the wrong one in. If everything is working, then you might want to adjust the freecap.php file again to limit the number of images to something more reasonable.

In The Future

It's highly possible that future upgrades of phpBB2 will overwrite your changes. If that happens, you can always start over at step 5. This should keep your boards spambot free!

Feedback & Help

If you need help or have feedback, you can try emailing me. But I don't make any promises that I'll have time to reply, and I won't be able to help you fix anything if you've broken something.