NAME
Mojolicious::Plugin::CaptchaPNG - PNG captcha generation and validation Mojolicious plugin
VERSION
version 1.08
SYNOPSIS
# Simple Mojolicious
$app->plugin( CaptchaPNG => { ttf => 'font.ttf' } );
my $captcha_value = $app->get_captcha_value;
my $success = $app->check_captcha_value($captcha_value);
$app->clear_captcha_value;
# Customized Mojolicious
$app->plugin( CaptchaPNG => {
routes => $app->routes,
method => 'any',
path => '/captcha',
key => '_plugin_captchapng',
width => 230,
height => 50,
ttf => 'font.ttf',
size => 20,
rotation => 8,
x => 20,
y_base => 35,
y_rotate => 100,
noise => 1_250,
background => [ 255, 255, 255 ],
text_color => [ 'urand(128)', 'urand(128)', 'urand(128)' ],
noise_color => [ 'urand(128) + 128', 'urand(128) + 128', 'urand(128) + 128' ],
min_entropy => 40,
value => sub {
return int(
Mojolicious::Plugin::CaptchaPNG::urand(
10_000_000 - 1_000_000
)
) + 1_000_000;
},
display => sub {
my ($display) = @_;
$display =~ s/^(\d{2})(\d{3})/$1-$2-/;
$display =~ s/(.)/ $1/g;
return $display;
},
} );
# Mojolicious::Lite
plugin( CaptchaPNG => { ttf => 'font.ttf' } );DESCRIPTION
This module is a Mojolicious plugin for basic image captcha generation and validation.
During registration (when plugin is called), the plugin will setup a route (which defaults to /captcha) that will respond with a generated PNG captcha. The image is generated using GD::Image. The plugin will also setup helper methods to get, check, and clear the captcha value, which is stored in the session.
Note that the assumption herein is that you're using Mojolicious verison 9.39 or higher with Mojolicious::Sessions's encrypted on. If so, the application's Mojolicious secrets are checked for strong entropy and a warning is issued if any have low entropy. (See min_entropy below.) If not, then its expected you'll provide your own captcha value encryption. (See encrypt and decrypt below.)
SETTINGS
Much of the plugin's settings are customizable, but only 1 is required.
ttf
This is the only setting that's required. It is the path to a TTF font file that will be used to generate the text in the captcha image.
routes
This a Mojolicious::Routes object. If not set, it defaults to:
$app->routesmethod
The value to use when setting up the route method. If not set, it defaults to any.
path
The value to use when setting up the route path. If not set, it defaults to /captcha.
key
When a captcha image is generated, the value of the captcha text is stored in the session under this key. If not set, it defaults to _plugin_captchapng.
width, height
The width and height of the generated captcha image. If not set, these default to 230 and 50 respectively.
size
The font size of the text in the captcha image. If not set, it defaults to 20.
rotation
The amount of rotation to be made to the text in the captcha image. If not set, it defaults to 8.
x
The x coordinate GD::Image uses for the text. If not set, it defaults to 20.
y_base
The base value used for y in GD::Image for the text. If not set, it defaults to 35.
y_rotate
The rotational value used for y in GD::Image for the text. If not set, it defaults to 100.
noise
The amount of noise to generate in the image. If not set, it defaults to 1_250.
background
An array reference of 3 expressions, which will be used to set the color of the background in the image. Values will be evaluated before used. If not set, it defaults to:
[ 255, 255, 255 ]text_color
An array reference of 3 expressions, which will be used to set the color of the text in the image. Values will be evaluated before used. If not set, it defaults to:
[ 'urand(128)', 'urand(128)', 'urand(128)' ]Note that urand is provided by this library. See below.
noise_color
An array reference of 3 valexpressionses, which will be used to set the color of the noise color in the image. Values will be evaluated before used. If not set, it defaults to:
[ 'urand(128) + 128', 'urand(128) + 128', 'urand(128) + 128' ]Note that urand is provided by this library. See below.
min_entropy
This is the minimum entropy level the application's Mojolicious secrets need to achieve to avoid this plugin logging a warning. The default threshold is 40.
Note that min_entropy is ignored if encrypt and decrypt are provided.
value
A subroutine reference that will be called to generate the value used for the text of the captcha. If not set, it defaults to:
sub {
return int(
Mojolicious::Plugin::CaptchaPNG::urand(
10_000_000 - 1_000_000
)
) + 1_000_000;
}display
A subroutine reference that will be called and passed a value. The subroutine is expected to alter the value for display purposes. For example, adding spaces or dashes or other such things. If not set, it defaults to:
sub {
my ($display) = @_;
$display =~ s/^(\d{2})(\d{3})/$1-$2-/;
$display =~ s/(.)/ $1/g;
return $display;
}encrypt, decrypt
If these are set to subroutine references, they will be called to encrypt and decrypt the value into and out of the session. They are passed the value to encrypt or decrypt.
HELPER METHODS
get_captcha_value
This method (expected to be used in a Mojolicious controller) will return the stored captcha value from the most recent image generation.
my $captcha_value = $app->get_captcha_value;set_captcha_value
This method (likely never used, but if used would be expected to be used in a Mojolicious controller) will set a captcha value.
$app->set_captcha_value(42);check_captcha_value
This method (expected to be used in a Mojolicious controller) expects a captcha value and will return true or false if it matches the stored captcha value.
my $success = $app->check_captcha_value($captcha_value);On success, the captcha value is removed from the session.
clear_captcha_value
Removes the captcha value from the session.
$app->clear_captcha_value;OTHER METHOD
urand
This method is a functional replacement of the core rand but using Crypt::URandom for randomness.
SEE ALSO
Mojolicious, Mojolicious::Plugin.
You can also look for additional information at:
AUTHOR
Gryphon Shafer <gryphon@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2025-2050 by Gryphon Shafer.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)