The CAPTCHA. Documentation

Contents:

  1. What is CAPTCHA?
  2. How to install The CAPTCHA
  3. How to use The CAPTCHA
  4. Troubleshooting

What is CAPTCHA?

If you're reading this document possibly you already know what is CAPTCHA. If you don't, please refer to articles on The CAPTCHA's official site at www.thecaptcha.com.


How to install The CAPTCHA

  1. Make sure your hosting meets the requirements: PHP4 or 5, GD 2.0. TTF support is optional, but recommended.
  2. Download The CAPTCHA library.
  3. Make a decision on where on your website you will place the library. The best choice is "/captcha" directory under document root of your website. In this case the url of the library's directory will be like this: "www.mysite.com/captcha/".
  4. Open files "captcha.function.php5" and "captcha.sampleform.php5" of this package in your favourite text editor. In file "captcha.function.php5" edit custom settings after line "CUSTOM SETTINGS". In file "captcha.sampleform.php5" change $myemail to your real email address.
  5. Upload all the library files to your hosting with your favourite FTP-client.
  6. Type the url of your site with the path to the library and sample form in your browser. For example: "www.mysite.com/captcha/captcha.sampleform.php5".

That's all. If you can't see the CAPTCHA image and this sample form is not working properly, please refer to the Troubleshooting section.


How to use The CAPTCHA

The CAPTCHA library consists these files:

captcha.function.php5
This file consists two functions: captcha_show_image() and captcha_verify_word(). The first outputs the image to browser and stores a CAPTCHA word in a cookie or a session file. Include the file captcha.function.php5 in your project with "include()" or "require()" statement. Example: if you plan to use CAPTCHA in file "myform.php5" place in the very first lines of the file this:
include("PATH_TO_CAPTCHA_DIRECTORY/captcha.function.php55");
Dont't forget to change PATH_TO_CAPTCHA_DIRECTORY to the real path to these CAPTCHA scripts.

The function captcha_verify_word() verifies a CAPTCHA word sent by user. It returns true if a word is correct, or false if user's input is incorrect. You can use the function like this:
if (!captcha_verify_word()) {
	die('Art thou a paltry spambot? Thy word is wrong!');
} else {
	// Let's process the form...
}
captcha.image.php5
This file, when called, shows a CAPTCHA image. To use it in your form see an example:
<form action="/script.php5" method="post">
...
<!-- Here is the call for the image. Make sure that url is correct -->
<img src="captcha.image.php5"><br>
<!-- This is a text input for CAPTCHA word -->
<input name="magicword" type="text" tabindex="4">
<button type="submit">Submit your comment</button>
</form>

Please note, that as captcha_show_image() function sends some HTTP headers and outputs the image, there must be no whitespaces, tabs or characters of any kind at all before the starting and after the closing php tags in the captcha.image.php5 file.

captcha.sampleform.php5
This is just an example, though a really working example, how to use The CAPTCHA library. Change $myemail to your real email address.
Font files
This library consists some True Type (.ttf) and GD (.gd) fonts to draw the letters over the image. If your hosting does not support True Type, then GD fonts will be used.
protected.png
This is a small black box with string "protected by thecaptcha.com" that is shown at the bottom of The CAPTCHA image if $captcha_show_credits is set to true. It's up to you, turn it to false if you don't like it.

Troubleshooting

I can't see the image. What's wrong?

I use a session method to store CAPTCHA word, but the captcha_verify_word() function tells me that word is wrong.