Customizing Securimage

Securimage is highly configurable. Nearly every visual aspect of the CAPTCHA image can be changed — colors, fonts, image dimensions, distortion level, line count, and character set. All configuration is done in securimage_show.php (recommended) or in the __construct() function of securimage.php.

All examples below assume you are editing securimage_show.php.

Changing Colors

Colors are set using the Securimage_Color class. You can pass RGB values or an HTML hex string:

<?php
// RGB values (0–255)
$color = new Securimage_Color(0, 0, 255); // blue

// Hex string
$color = new Securimage_Color('#3388FF');

// Shorthand hex
$color = new Securimage_Color('#38F');

To change the background, text, and line colors of the CAPTCHA image:

<?php
// In securimage_show.php, before $img->show()

$img->image_bg_color = new Securimage_Color('#ffffff'); // white background
$img->text_color     = new Securimage_Color('#525252'); // dark grey text
$img->line_color     = new Securimage_Color('#525252'); // matching line color

Using Background Images

Securimage can use a single static background image, or pick randomly from a directory. Backgrounds should ideally match the image size (230×80px by default) but will be resized if they don't.

To use a single background image, pass its full path to the show() method:

<?php
// Last line of securimage_show.php — full path required
$img->show('/home/user/public/securimage/backgrounds/image.png');

// Windows path
$img->show('C:\\inetpub\\wwwroot\\securimage\\backgrounds\\image.png');

To use random backgrounds from a directory:

<?php
// Set background directory (dirname resolves the path automatically)
$img->background_directory = dirname(__FILE__) . '/backgrounds/';

Place your PNG, JPG, or GIF images in the backgrounds/ folder inside the Securimage directory. Securimage ships with a few sample backgrounds — add as many of your own as you like.

Adjusting Difficulty

Two settings control how hard the CAPTCHA is for bots to solve: character distortion and random line overlays.

Distortion is controlled by the perturbation property (0 = none, 1 = maximum). The default is 0.75. Values above 1 are not recommended as they make the image difficult for humans.

Lines are controlled by num_lines. More lines = harder for bots but also harder for users.

<?php
// Default distortion
$img->perturbation = 0.75;

// High distortion — use carefully
$img->perturbation = 1.0;

// No distortion — easiest to read
$img->perturbation = 0;

// Many lines over the image
$img->num_lines = 10;

// No lines
$img->num_lines = 0;

Custom Fonts

Securimage supports any TTF font. Using a unique font makes your CAPTCHA harder for bots trained on the default font. Upload the TTF file to the Securimage folder (where AHGBold.ttf is located) — avoid spaces or special characters in the filename.

<?php
// Use a custom TTF font from the securimage directory
$img->ttf_file = $img->basepath . '/myfont.ttf';

// Or with an absolute path if the font is elsewhere
$img->ttf_file = '/home/user/public/fonts/myfont.ttf';

Adding a Signature

A signature is small text shown in the bottom-right corner of every CAPTCHA image — useful for branding with your domain name.

<?php
$img->image_signature = 'yoursite.com';
$img->signature_color = new Securimage_Color('#000000'); // black

Adjusting Image Size

Change image_width and image_height to resize the CAPTCHA. For best results, keep the width at least 2.7× the height so the characters have room to render.

<?php
// Set width, calculate optimal height
$img->image_width  = 260;
$img->image_height = (int)($img->image_width * 0.35); // = 91px

// Or set height and calculate width
$img->image_height = 50;
$img->image_width  = (int)($img->image_height * 2.875); // = 143px

Changing the Character Set

By default, Securimage uses a subset of [a-zA-Z0-9] with ambiguous characters excluded (I, J, O, Q, i, j, o, q, 0, 1). You can override this with any string of characters.

<?php
// Capital letters only
$img->charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';

// Numbers only
$img->charset = '0123456789';

// Lowercase and numbers, excluding ambiguous characters
$img->charset = 'abcdefghklmnprstuvwyz23456789';

Note: repeating a character in the charset increases its probability of appearing.

Randomizing Properties

Randomizing properties between image loads makes your CAPTCHA harder for bots to adapt to, since they can't make assumptions about fixed code length or line count.

<?php
// Variable code length (4 to 6 characters)
$img->code_length = rand(4, 6);

// Random number of lines
$img->num_lines = rand(3, 10);

Related