Captch...APTCHA(3pm)

🌸 Captch...APTCHA(3pm) — User Contributed Perl Documentation 🌸

okay so bestie, welcome to the Captch...APTCHA(3pm) page from User Contributed Perl Documentation. This is literally the manual for Captcha::reCAPTCHA, and it's giving “Perl module that talks to reCAPTCHA.” We're doing this in two parts, so buckle up. 🎀

💖 NAME 💖

Captcha::reCAPTCHA — A Perl implementation of the reCAPTCHA API. Periodt. 👑

✨ VERSION ✨

This document describes Captcha::reCAPTCHA version 0.98.

🚨 NOTICE 🚨

Please note: this module now allows the use of v2. There are no changes to version 1. Version 2 has separate methds you can call. (Yes, methds. We love a typo with main character energy. 💅)

🦋 SYNOPSIS 🦋

Note this release contains methods that use 👀:

use Captcha::reCAPTCHA;

my $c = Captcha::reCAPTCHA->new;

# Output form New Version
print $c->get_html_v2( 'your public key here' );

# Version 1 (not recommended)
print $c->get_html( 'your public key here' );

# Verify submission
my $result $c->check_answer_v2($private_key, $response, $ENV{REMOTE_ADDR});

# Verify submission (Old Version)
my $result = $c->check_answer(
    'your private key here', $ENV{'REMOTE_ADDR'},
    $challenge, $response
);

if ( $result->{is_valid} ) {
    print "Yes!";
}
else {
    # Error
    $error = $result->{error};
}

For complete examples see the /examples subdirectory. 🫶

🌈 DESCRIPTION 🌈

reCAPTCHA version 1 is a hybrid mechanical turk and captcha. It lets visitors who complete the captcha help digitize books. No, fr fr — that's the whole vibe. 📚

From <http://recaptcha.net/learnmore.html>:

reCAPTCHA improves the process of digitizing books by sending words that cannot be read by computers to the Web in the form of CAPTCHAs for humans to decipher. More specifically, each word that cannot be read correctly by OCR is placed on an image and used as a CAPTCHA. This is possible because most OCR programs alert you when a word cannot be read correctly.

The version 1 Perl implementation is modelled on the PHP interface that can be found here:

<http://recaptcha.net/plugins/php/>

To use reCAPTCHA you need to register your site here:

<https://www.google.com/recaptcha/admin/create>

Version 2 is a new and eaasy to solve captcha that is "easy for humans to solve, but hard for 'bots' and other malicious software". (Again, eaasy is in the original and we are not fixing it. Iconic.)

👑 INTERFACE 👑

💅 new

Creates a new Captcha::reCAPTCHA. Slay. ✨

🎀 get_options_setter( $options )

You can optionally customize the look of the reCAPTCHA widget with some JavaScript settings. get_options_setter returns a block of Javascript wrapped in <script> .. </script> tags that will set the options to be used by the widget.

$options is a reference to a hash that may contain the following keys:

• theme — Defines which theme to use for reCAPTCHA. Possible values are 'red', 'white' or 'blackglass'. The default is 'red'.
• tabindex — Sets a tabindex for the reCAPTCHA text box. If other elements in the form use a tabindex, this should be set so that navigation is easier for the user. Default: 0.

🦋 get_options_setter_div( $pubkey, $options )

You can optionally customize the look of the reCAPTCHA widget with some settings. get_options_setter_div returns a div element wrapped in <div> .. </div> tags that will set the options to be used by the widget.

$options is a reference to a hash that may contain the following keys:

• data-theme — Defines which theme to use for reCAPTCHA. Possible values are 'dark', 'light'. The default is 'light'.
• data-type — Defines the type of captcha to server. Possible values are 'audio' or 'image'. Default is 'image'.
• data-size — Defines the size of the widget. Possible values are 'compact' or 'normal'. Default is 'normal'.
• data-tabindex — Defines the tabindex of the widget and challenge. If other elements in your page use tabindex, it should be set to make user navigation easier. Default is 0.
• data-callback — Defines the name of your callback function to be executed when the user submits a successful CAPTCHA response. The user's response, g-recaptcha-response, will be the input for your callback function.
• data-expired-callback — Defines the name of your callback function to be executed when the recaptcha response expires and the user needs to solve a new CAPTCHA.

⭐ get_html_v2( $pubkey, \%options )

Generates HTML to display the captcha using the new api. pubkey is the public key for \%options; the types are the same as get_options_setter.

print $captcha->get_html_v2($pubkey, $options);

This uses ssl by default and does not display custom error messages. 🔥

💜 get_html( $pubkey, $error, $use_ssl, \%options )

Generates HTML to display the captcha using api version 1.

print $captcha->get_html( $PUB, $err );

• $pubkey — Your reCAPTCHA public key, from the API Signup Page.
• $error — Optional. If set this should be either a string containing a reCAPTCHA status code or a result hash as returned by check_answer.
• $use_ssl — Optional. Should the SSL-based API be used? If you are displaying a page to the user over SSL, be sure to set this to true so an error dialog doesn't come up in the user's browser.
• $options — Optional. A reference to a hash of options for the captcha. See get_options_setter for more details.

Returns a string containing the HTML that should be used to display the captcha. 💖

💖 DISCLAIMER OF WARRANTY 💖

ok so here's the part nobody reads until something breaks, and bestie, you gotta read it. Free software means free-as-in-no-one-owes-you-anything, and the license says it in the loudest font possible (all caps, because lawyers love yelling). Here's the whole thing, word for word, no skips:

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

Translation for the group chat 🫶: it's "AS IS", there is no warranty of any kind, either expressed or implied, and if it's cooked, you pay for the servicing, repair, or correction. The risk is literally on you, babe. Not on the copyright holders, not on the other parties — you.

And then the second half, the "please don't sue us" half:

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

So like, the full damage list, because lawyers are thorough girlies:

• general, special, incidental, or consequential damages — yes, all four flavours 😭
• damages arising out of the use or inability to use the software (both directions, they really thought of everything)
• loss of data or data being rendered inaccurate
• losses sustained by you or third parties
• a failure of the software to operate with any other software

…and this holds even if the holder or other party has been advised of the possibility of such damages. So no "but I told you it was fragile!!" defence, and tbh no "you should've warned me" claim either. 💀

Key vibe: the entire risk as to quality and performance is yours, and liability only kicks in if applicable law requires it or somebody agreed to it in writing. Everything else is "AS IS", bestie. No cap.

---

so yeah, that's the whole page 🎀 go be iconic with it, and please for the love of everything back up your data — that's the real warranty. 💅✨

this little legend came from perl v5.36.0, dated 2022-11-19, and lives under the gorgeous name Captch...APTCHA(3pm) 🦋 (yes that's the actual truncated manpage title, we stan an aesthetic filename). mwah, bye bestie 💜🧚