NAME

Image::VisualConfirmation - Add anti-spam CAPTCHA ( visual confirmation/challenge) to your web forms.

SYNOPSIS

    use Image::VisualConfirmation;
    
    my $vc = Image::VisualConfirmation->new();
    
    # ### Get code and image ####
    
    print $vc->image_code;
    
    my $image_data = $vc->image_data(type => 'png');
    
    # ### Work with the Imager object directly ###
    
    my $image = $vc->image;
    $image->filter(type=>'turbnoise'):
    
    $vc->image->write(file => 'vc.jpg');
    

DESCRIPTION

This module aims at making the creation of visual confirmation (also known as visual challenge) images simple. For those who doen't know about these, they are the funky images from which you have to copy the text when submitting a form. Their function is to avoid robots spamming web forms, and they work quite good even though spammers' OCR software is becoming increasingly good.

This module is mainly for use in a web application context, in conjuction with such modules as CGI::Session or with a web framework such as Catalyst.

When creating the random string, this module excludes the letters/digits which might be confused with each other, so that the user has a greater chance to not get angered with the challenge: 0, upper and lower-case o; lower-case l and 1; j.

This module is in many ways similar to Authen::Captcha, but is uses Imager instead of GD and it features a different interface: it's simpler, just a lightweight wrapper around Imager). And there's also GD::SecurityImage. Choose the module that better suits your needs.

An usage example is available in the examples directory.

METHODS

new

Arguments: \%options

Return Value: $vc (new Image::VisualConfirmation object)

This method initializes a new object.

    # This should work everywhere
    my $vc = Image::VisualConfirmation->new();

    # Font selection on Win32
    my $vc = Image::VisualConfirmation->new({
        font_file   => './bodoni.pbf',
        font_size   => 30,
    });
    
    # Font selection on all other systems (should work on Win32 as well)
    my $vc = Image::VisualConfirmation->new({
        font_face   => 'Times New Roman',
        font_size   => 30,
    });

All parameters are optional:

font_face: under Win32, this is the standard method to specify the font to use to render the text. You can specify the font with or without attributes, i.e. Times New Roman or Arial Bold. If this parameter is not passed, it defaults to Arial on Win32 and is completely ignored on other systems.

font_file: the path to the font to use to render the text. By default it uses a Bitstream Vera font bundled with this module, unless you are on Win32 where your system Arial font will be used. Several font formats are accepted, depending on your platform: see Imager::Font documentation. The bundled Vera font is in /your/perllib/path/Image/VisualConfirmation/Vera.ttf or some similar location, and you should have plenty of fonts to choose from in /usr/share/fonts.

font_size: the size of the characters, it defaults to 20.

font_type: it has been reported the font-type autodetection by Imager doesn't always work, so you have the options to explicitly tell the the font type: available types depend on how Imager is compiled on your system, but they should be tt, t1, w32, ft2 or a subset of these. This parameter is only considered when font_file is specified as well. It is highly recommended that you pass this parameter if you pass a font_file (you might get font file not found from Imager errors otherwise).

code_length: the length, in chars, of the visual code to generate at random; default is 6.

code: allows to provide a code to display on the image, instead of generating one at random. You can also pass a coderef of any sub that returns a string.

width and height: if these 2 are provided, the image will be createt of that size (but rotation might then change it a bit); otherwise, the size will be calculated dinamically depending on code_length and font_size.

create_new_image

Arguments: \%options

Generates a new code and new image for the given object. Parameters are the same as new.

code

Returns: string

Returns the code which has been generated, in string format. This is needed for comparison with the user-entered one.

image

Returns: Imager object

Returns an Imager object with the created image. This allows you to get all the image properties, save it, ... It also allows to perform further obfuscation on the image, if needed.

image_data

Arguments: \%options

Returns: raw image data

This method returns the raw data of the image in a variable, which can be used for direct output, i.e.:

    my $image_data = $vc->image_data;
    
    print $q->header(
        type   => 'image/png',
    );

    print $image_data;

There's an optional parameter, type, which allows you to specify the format of the data you get. All formats supported by Imager are valid: png (the default if you don't pass the parameter), jpeg, gif, tiff, bmp, tga and raw. Beware that gif support is broken on some platforms (including mine): don't use it. You can pass any additional parameter that Imager's write method accepts, it will be forwarded: see Imager::Files for more information.

TODO

- Make width and height actually work as expected.

- Improve the visual challenge by adding image deformations.

- Improve the synopsis with a CGI::Session and a Catalyst example.

- Improve error handling with bad parameters.

SEE ALSO

Imager

AUTHOR

Michele Beltrame, mb@italpro.net

LICENSE

This library is free software, you can redistribute it and/or modify it under the same terms as Perl 5 itself.

The Bitstream Vera font bundled with this distribution is copyrighted by Bitstream ( http://www.bitstream.com ) and distributed under its license terms.

cpanm Image::VisualConfirmation

perl -MCPAN -e shell
install Image::VisualConfirmation