NAME

Dancer2::Plugin::Captcha - Dancer2 add-on for CAPTCHA.

VERSION

Version v1.0.0

DESCRIPTION

A very simple plugin for Dancer2 to process CAPTCHA.I needed this for my other project (in-progress) available on github.

The core functionality of the plugin is supported by GD::SecurityImage.

SYNOPSIS

Setting up the application configuration.

The plugin expect a session engine configured for it to perform its task,

session: Simple

plugins:
  Captcha:
    new:
      width: 160
      height: 175
      lines: 5
      gd_font: 'giant'
    create: [ 'normal', 'default' ]
    out:
      force: 'png'
    particle: [ 100 ]

Setting up the application route handler.

get '/get_captcha' => sub {
    return generate_captcha();
};

post '/validate_captcha' => sub {
    return "Invalid captcha code."
        unless (is_valid_captcha(request->params->{captcha}));

    remove_captcha;
};

Setting up the application template.

<form method="POST" action="/validate_captcha">
    <label>Enter the Captcha</label>
    <input type="text" name="captcha" style="width: 120px;">
    <img id="img1" src="<% request.uri_base %>/get_captcha" style="margin-bottom:20px;">
    <button type="submit">Submit</button>
</form>

CONFIGURATION

The plugin can be configured in the application configuration file as below:

plugins:
  Captcha:
    new:
    create:
    particle:
    out:

new

The following keys can be assigned to method 'new':

+------------+--------------------------------------------------------------+
| Key        | Description                                                  |
+------------+--------------------------------------------------------------+
| width      | The width of the image (in pixels).                          |
| height     | The height of the image (in pixels).                         |
| ptsize     | The point size of the ttf character.                         |
| lines      | The number of lines in the background of the image.          |
| font       | The absolute path to your TrueType font file.                |
| gd_font    | The possible value are 'small', 'large', 'mediumbold',       |
|            | 'tiny' and 'giant'.                                          |
| bgcolor    | The background color of the image.                           |
| send_ctobg | If has a true value, the random security code will be        |
|            | displayed in the background and the lines will pass over it. |
| frame      | If has a true value, a frame will be added around the image. |
| scramble   | If set, the characters will be scrambled.                    |
| angle      | Sets the angle (0-360) for scrambled/normal characters.      |
| thickness  | Sets the line drawing width.                                 |
| rndmax     | The minimum length if the random string. Default is 6.       |
| rnd_data   | Default character set used to create the random string is    |
|            | [0..9].                                                      |
+------------+--------------------------------------------------------------+

See "new" in GD::SecurityImage for more details.

create

The data should be in the format as below for method 'create':

[ $method, $style, $text_color, $line_color ]

The key $method and $style are mandatory and the rest all are optionals.

The key $method can have one of the following values:

normal or ttf

The key $style can have one of the following values:

+---------+-----------------------------------------------------------------+
| Key     | Description                                                     |
+---------+-----------------------------------------------------------------+
| default | The default style. Draws horizontal, vertial and angular lines. |
| rect    | Draws horizontal and vertical lines.                            |
| box     | Draws two filled rectangles.                                    |
| circle  | Draws circles.                                                  |
| ellipse | Draws ellipses.                                                 |
| ec      | Draws both ellipses and circles.                                |
| blank   | Draws nothing.                                                  |
+---------+-----------------------------------------------------------------+

out

The following keys can be assigned to method 'out':

+----------+----------------------------------------------------------------+
| Key      | Description                                                    |
+----------+----------------------------------------------------------------+
| force    | Can have one of the formats 'jpeg' or 'png' or 'gif'.          |
| compress | Can be between 1 and 100.                                      |
+----------+----------------------------------------------------------------+

particle

The data should be in the format as below for method 'particle':

[ $density, $maximum_dots ]

The default value for $density is dependent on the image's height & width. The greater value of height and width is taken and multiplied by 20 for defaults.

The key $maximum_dots defines the maximum number of dots near the default dot. The default value is 1. If you set it to 4, the selected pixel and 3 other pixels near it will be used and colored.

METHODS

generate_captcha(\%params, $id)

It returns captcha image as per the given parameters and $id is the captcha ID (optional, default value is 'default'). If the key 'random' is not defined then the default character sets [0..9] will be used.

get '/get_captcha' => sub {
    return generate_captcha({
        new => {
            width   => 500,
            height  => 75,
            lines   => 5,
            gd_font => 'giant',
        },
        particle => [ 100 ],
        out      => { force => 'png' },
        random   => <your_randomly_generated_string>,
    });
};

is_valid_captcha($input, $id)

The $input is the captcha code entered by the user and $id is the captcha ID (optional, default value is 'default'). It returns 0 or 1 depending on whether the captcha matches or not.

post '/validate_captcha' => sub {
    return "Invalid captcha code."
        unless (is_valid_captcha(request->params->{captcha}));

    remove_captcha;
};

remove_captcha($id)

The $id is the captcha ID (optional, default value is 'default'). It removes the captcha from the session.

AUTHOR

Mohammad S Anwar, <mohammad.anwar at yahoo.com>

REPOSITORY

https://github.com/manwar/Dancer2-Plugin-Captcha

ACKNOWLEDGEMENTS

Inspired by the package Dancer::Plugin::Captcha::SecurityImage (Alessandro Ranellucci <aar@cpan.org>).

SEE ALSO

Dancer::Plugin::Captcha::SecurityImage, GD::SecurityImage

BUGS

Please report any bugs or feature requests through the web interface at https://github.com/manwar/Dancer-Plugin-Captcha/issues. I will be notified and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Dancer2::Plugin::Captcha

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright (C) 2015 - 2026 Mohammad Sajid Anwar.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0).