/ 
Dancer2-Plugin-Captcha-0.14
River stage zero No dependents
/ Dancer2::Plugin::Captcha

NAME

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

VERSION

Version 0.14

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 to bug-dancer2-plugin-captcha at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dancer2-Plugin-Captcha. 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 - 2019 Mohammad S Anwar.

This program is free software; you can redistribute it and / or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License.By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you,you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement,then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.