The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-ZofCMS-PluginBundle-Naughty-1.001002
River stage zero No dependents
++
/ App::ZofCMS::Plugin::Captcha

NAME

App::ZofCMS::Plugin::Captcha - plugin to utilize security images (captchas)

SYNOPSIS

    plugins => [
        { Session => 1000 },
        { Captcha => 2000 },
    ],
    plugins2 => [
        qw/Session/
    ],

    plug_captcha => {},

    # Session plugin configuration (i.e. database connection is left out for brevity)

DESCRIPTION

The module is a plugin for App::ZofCMS that provides means to generate and display security images, known as "captchas" (i.e. protecting forms from bots).

The plugin was coded with idea that you will be using App::ZofCMS::Plugin::Session along with it to store the generated random string; however, it's not painfully necessary to use Session plugin (just easier with it).

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins

    plugins => [
        { Session => 1000 },
        { Captcha => 2000 },
    ],
    plugins2 => [
        qw/Session/
    ],

Mandatory. You need to include the plugin in the list of plugins to execute. I'm using Session plugin here to first load existing session and after Captcha is ran, to save the session.

plug_captcha

    # all defaults
    plug_captcha => {},

    # set all arguments
    plug_captcha => {
        string  => 'Zoffix Znet Roxors',
        file    => 'captcha.gif',
        width   => 80,
        height  => 20,
        lines   => 5,
        particle => 0,
        no_exit => 1,
        style   => 'rect',
        format  => 'gif',
        tcolor  => '#895533',
        lcolor  => '#000000',
    },

    # or set some via a subref
    plug_captcha => sub {
        my ( $t, $q, $config ) = @_;
        return {
            string  => 'Zoffix Znet Roxors',
            file    => 'captcha.gif',
        }
    },

Mandatory. Takes either a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_captcha as if it was already there. If sub returns an undef, then plugin will stop further processing. The @_ of the subref will contain (in that order): ZofCMS Template hashref, query parameters hashref and App::ZofCMS::Config object. To run the plugin with all the defaults, use an empty hashref. Possible keys/values for the hashref are as follows:

string

    plug_captcha => {
        string  => 'Zoffix Znet Roxors',
    },

Optional. Specifies the captcha string. Takes either a scalar string or undef. If set to undef, the plugin will generate a random numeric string. Defaults to: undef.

file

    plug_captcha => {
        file    => 'captcha.gif',
    },

Optional. Takes either a scalar string or undef as a value. If set to a string, it represents the name of the file into which to save the captcha image (relative to index.pl). If set to undef, plugin will output correct HTTP headers and the image directly into the browser. Defaults to: undef.

no_exit

    plug_captcha => {
        no_exit => 1,
    },

Optional. This one is relevant only when file (see above) is set to undef. Takes either true or false values. If set to a false value, plugin will call exit() as soon as it finishes outputting the image to the browser. You'd use it if you're generating your own string and are able to store it with the Session plugin before Captcha plugin runs. If set to a true value, plugin will not call exit() and the runcycle will continue; this way the Captcha plugin generated random string can be stored by Session plugin later in the runlevel. Note: that in this case, after the image is printed the browser will also send some garbage (and by that I mean the standard HTTP Content-type headers that ZofCMS prints along with whatever may be in your template); even though I haven't noticed that causing any problems with the image, if it does cause broken image for you, simply use App::ZofCMS::Plugin::Sub and call exit() within it. Defaults to: 1

width

    plug_captcha => {
        width   => 80,
    },

Optional. Takes a positive integer as a value. Specifies captcha image's width in pixels. Defaults to: 80

height

    plug_captcha => {
        height  => 20,
    },

Optional. Takes a positive integer as a value. Specifies captcha image's height in pixels.Defaults to: 20

lines

    plug_captcha => {
        lines   => 5,
    },

Optional. Specifies the number of crypto-lines to generate. See GD::SecurityImage for more details. Defaults to: 5

particle

    plug_captcha => {
        particle => 0, # disable particles
    },

    plug_captcha => {
        particle => 1, # let plugin decide the right amount
    },

    plug_captcha => {
        particle => [40, 50], # set amount yourself
    },

Optional. Takes either false values, true values or an arrayref as a value. When set to an arrayref, the first element of it is density and the second one is maximum number of dots to generate - these dots will add more cryptocrap to your captcha. See particle() method in GD::SecurityImage for more details. When set to a true value that is not an arrayref, GD::SecurityImage will try to determine optimal number of particles. When set to a false value, no extra particles will be created. Defaults to: 0

style

    plug_captcha => {
        style   => 'rect',
    },

Optional. Specifies the cryptocrap style of captcha. See GD::SecurityImage create() method for possible styles. Defaults to: rect

format

    plug_captcha => {
        format  => 'gif',
    },

Optional. Takes string gif, jpeg or png as a value. Specifies the format of the captcha image. Some formats may be unavailable depending on your GD version. Defaults to: gif

tcolor

    plug_captcha => {
        tcolor  => '#895533',
        lcolor  => '#000000',
    },

Optional. Takes 6-digit hex RGB notation as a value. Specifies the color of the text (and particles if they are on). Defaults to: #895533

lcolor

    plug_captcha => {
        lcolor  => '#000000',
    },

Optional. Takes 6-digit hex RGB notation as a value. Specifies the color of cryptocrap lines. Defaults to: #000000

OUTPUT

    $t->{d}{session}{captcha} = 'random_number';

    $t->{t}{plug_captcha_error} = 'error message';

Plugin will put the captcha string into $t->{d}{session}{captcha} where $t is ZofCMS Template hashref. Currently there is no way to change that.

If you're saving captcha to a file, possible I/O error message will be put into $t->{t}{plug_captcha_error} where $t is ZofCMS Template hashref.

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS-PluginBundle-Naughty

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS-PluginBundle-Naughty/issues

If you can't access GitHub, you can email your request to bug-App-ZofCMS-PluginBundle-Naughty at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.