Securimage FAQ

Real questions from Securimage users over the years, with answers. If you're having trouble getting Securimage working, start here.

Fatal error: Call to undefined function imagecreatetruecolor()

This error means PHP's GD extension is either not installed or not enabled. To check:

  1. Upload the server_test.php file from the Securimage package and open it in a browser
  2. It will report whether GD is enabled and which features are available

On Windows: Edit your php.ini and uncomment the line ;extension=php_gd2.dll by removing the semicolon. Restart your web server.

On Linux (Ubuntu/Debian):

sudo apt-get install php-gd
sudo systemctl restart apache2   # or nginx + php-fpm

If GD is enabled but you get the error anyway, your GD version may be too old. Try changing imagecreatetruecolor to imagecreate in securimage.php as a workaround.

Fatal error: Call to undefined function imagettftext()

GD is enabled but FreeType (TTF font) support is not compiled in. This is shown in the server test output as "TTF Support (FreeType): No".

On Linux, install the FreeType-enabled GD:

sudo apt-get install php-gd libgd3 libfreetype6-dev
sudo systemctl restart php8.1-fpm   # match your PHP version

Alternatively, configure Securimage to use GD fonts instead of TTF by setting $img->use_gd_font = true; in securimage_show.php. The image quality will be lower but it will work without FreeType.

CAPTCHA fails on my live server but works locally

This is almost always a session issue. The most common cause: your form processor outputs HTML before session_start() is called, which prevents the session from starting.

Fix: Make the very first line of your form processor:

<?php session_start(); ?>

This must appear before any HTML output, whitespace, or other PHP code. Even a blank line before <?php can cause headers-already-sent errors on some servers.

To debug: Add this at the top of both your form processor and securimage.php:

<?php
error_reporting(E_ALL);
ini_set('display_errors', 'on');

This will show you exactly what error is occurring and where.

The code is always invalid, even when typed correctly

Several things can cause this:

  1. Session not starting — see the answer above about session_start()
  2. GET vs POST mismatch — if your form uses method="get", change $_POST['captcha_code'] to $_GET['captcha_code'] in your form processor
  3. Checking the code too early — if you validate the CAPTCHA before all other form checks, the session code gets consumed even when there are other errors. Put the CAPTCHA check last, or only check it if all other fields are valid
  4. Image refreshed after submission — each time the CAPTCHA image loads, a new code is generated. If your form refreshes the image on error, the previous code is no longer valid

CAPTCHA fails when user hits the browser back button

When the user goes back and resubmits, the code displayed on screen is the old code but Securimage has already generated a new one (or cleared the old one). This is by design for security — a code can only be used once.

The cleanest solution is to invalidate form results on browser back: use header('Cache-Control: no-store, no-cache, must-revalidate') in your form processor to prevent caching. On back-navigation, the form reloads fresh with a new CAPTCHA.

Alternatively, don't clear the session code on a failed validation — only clear it on success. This is riskier from a security perspective but improves usability.

My form processor shows a blank page after submission

A blank page almost always means a PHP error is occurring but error display is turned off. Enable error reporting at the top of your processor:

<?php
error_reporting(E_ALL);
ini_set('display_errors', 'on');

Once you see the error message, the fix is usually straightforward.

How do I use a background image?

Pass the full path to your background image as a parameter to $img->show() in securimage_show.php:

<?php
// Last line of securimage_show.php
$img->show('/full/path/to/securimage/backgrounds/bg.jpg');

The background must be in PNG, JPG, or GIF format. It will be resized if it doesn't match the image dimensions. For random backgrounds from a directory, see the customization guide.

How do I enable the audio CAPTCHA?

The audio WAV files are not included in the main Securimage package — they must be downloaded separately from the GitHub releases page (audio.zip). Upload the extracted files to your Securimage directory.

In securimage_show.php, set the audio path:

<?php
$img->audio_path = dirname(__FILE__) . '/audio/';

For the HTML audio button, add a link or button that calls the Securimage audio URL with the same session ID as the image.

Image not displaying on GoDaddy hosting

GoDaddy and some other shared hosts inject HTML footer advertising code into PHP output. This corrupts the CAPTCHA image because the image bytes get mixed with HTML.

The fix: add a .htaccess file in the Securimage directory:

AddType application/x-httpd-php .png

Then rename securimage_show.php to securimage_show.png and update your image tag accordingly. The hosting provider's injection script typically won't modify PNG files.

Integrating with Smarty templates

In your Smarty template file, add the image tag and input field:

<img src="/securimage/securimage_show.php" alt="CAPTCHA" />
<input type="text" name="captcha_code" />

In your PHP form processor (the Smarty controller), do the validation:

<?php
session_start();
include 'securimage.php';

$img = new Securimage();
$code = $_POST['captcha_code'];

if ($img->check($code) == false) {
    // Code incorrect — re-display form with error
}

Will two users interfere with each other's CAPTCHA codes?

No. Each CAPTCHA code is stored in PHP's session, which is unique per user (based on a session cookie). User A's code is completely separate from User B's code. The only thing to be aware of: each user can only have one active code at a time. If a user loads the CAPTCHA image twice, only the second code is valid.

Changing code_length doesn't work

This was a bug in early versions of Securimage. If you're on an older version, upgrade to the latest release from GitHub. In current versions, $img->code_length = 6; in securimage_show.php works correctly.

PHP source code is showing instead of the CAPTCHA image

This means PHP is not installed or not configured to process PHP files on your server. Create a file called info.php with <?php phpinfo(); ?> and open it in a browser. If you see the PHP source code instead of a PHP info table, PHP is not running on your server.

Contact your hosting provider to enable PHP, or check that your web server is configured to process .php files.

How do I make the "different image" link work?

Add a JavaScript onclick to an anchor tag that updates the img element's src with a new random query string parameter. This forces the browser to re-request the image (which generates a new code):

<a href="#" onclick="
  document.getElementById('captcha').src =
  '/securimage/securimage_show.php?' + Math.random();
  return false">[ Different Image ]</a>

Is Securimage compatible with PHP 8?

Yes. The current version on GitHub supports PHP 7.2 through PHP 8.x. If you're on a very old version of Securimage (pre-3.0), upgrade from GitHub.

Do I have to use an image CAPTCHA?

Not at all. For many sites, a honeypot hidden field stops the vast majority of spam bots with zero user friction. For more serious bot protection, Cloudflare Turnstile is completely invisible and free. See our CAPTCHA alternatives guide for a full comparison.

Still having trouble?

Check the GitHub issues page — many edge-case problems have been reported and solved there. For the quickstart guide or customization options, see the documentation section.