{
    "mode": "perldoc",
    "parameter": "Authen::Captcha",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Authen%3A%3ACaptcha/json",
    "generated": "2026-06-09T15:22:27Z",
    "synopsis": "use Authen::Captcha;\n# create a new object\nmy $captcha = Authen::Captcha->new();\n# set the datafolder. contains flatfile db to maintain state\n$captcha->datafolder('/some/folder');\n# set directory to hold publicly accessible images\n$captcha->outputfolder('/some/http/folder');\n# Alternitively, any of the methods to set variables may also be\n# used directly in the constructor\nmy $captcha = Authen::Captcha->new(\ndatafolder => '/some/folder',\noutputfolder => '/some/http/folder',\n);\n# create a captcha. Image filename is \"$token.png\"\nmy $token = $captcha->generatecode($numberofcharacters);\n# check for a valid submitted captcha\n#   $code is the submitted letter combination guess from the user\n#   $token is the submitted token from the user (that we gave them)\nmy $results = $captcha->checkcode($code,$token);\n# $results will be one of:\n#          1 : Passed\n#          0 : Code not checked (file error)\n#         -1 : Failed: code expired\n#         -2 : Failed: invalid code (not in database)\n#         -3 : Failed: invalid code (code does not match token)\n##############",
    "sections": {
        "NAME": {
            "content": "Authen::Captcha - Perl extension for creating captcha's to verify the human element in\ntransactions.\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Authen::Captcha;\n\n# create a new object\nmy $captcha = Authen::Captcha->new();\n\n# set the datafolder. contains flatfile db to maintain state\n$captcha->datafolder('/some/folder');\n\n# set directory to hold publicly accessible images\n$captcha->outputfolder('/some/http/folder');\n\n# Alternitively, any of the methods to set variables may also be\n# used directly in the constructor\n\nmy $captcha = Authen::Captcha->new(\ndatafolder => '/some/folder',\noutputfolder => '/some/http/folder',\n);\n\n# create a captcha. Image filename is \"$token.png\"\nmy $token = $captcha->generatecode($numberofcharacters);\n\n# check for a valid submitted captcha\n#   $code is the submitted letter combination guess from the user\n#   $token is the submitted token from the user (that we gave them)\nmy $results = $captcha->checkcode($code,$token);\n# $results will be one of:\n#          1 : Passed\n#          0 : Code not checked (file error)\n#         -1 : Failed: code expired\n#         -2 : Failed: invalid code (not in database)\n#         -3 : Failed: invalid code (code does not match token)\n##############\n",
            "subsections": []
        },
        "WARNING": {
            "content": "The captcha produced by this module is rather weak compared to other modules available. You are\nadvised to update to GD::SecurityImage, which provides API-compatible interface in\nGD::SecurityImage::AC module.\n",
            "subsections": []
        },
        "ABSTRACT": {
            "content": "Authen::Captcha provides an object oriented interface to captcha file creations. Captcha stands\nfor Completely Automated Public Turing test to tell Computers and Humans Apart. A Captcha is a\nprogram that can generate and grade tests that:\n\n- most humans can pass.\n- current computer programs can't pass\n\nThe most common form is an image file containing distorted text, which humans are adept at\nreading, and computers (generally) do a poor job. This module currently implements that method.\nWe plan to add other methods, such as distorted sound files, and plain text riddles.\n",
            "subsections": []
        },
        "REQUIRES": {
            "content": "GD          (see http://search.cpan.org/~lds/GD-2.11/)\nDigest::MD5 (standard perl module)\n\nIn most common situations, you'll also want to have:\n\nA web server (untested on windows, but it should work)\ncgi-bin or mod-perl access\nPerl: Perl 5.00503 or later must be installed on the web server.\nGD.pm (with PNG support)\n",
            "subsections": []
        },
        "INSTALLATION": {
            "content": "Download the zipped tar file from:\n\nhttp://search.cpan.org/search?dist=Authen-Captcha\n\nUnzip the module as follows or use winzip:\n\ntar -zxvf Authen-Captcha-1.xxx.tar.gz\n\nThe module can be installed using the standard Perl procedure:\n\nperl Makefile.PL\nmake\nmake test\nmake install    # you need to be root\n\nWindows users without a working \"make\" can get nmake from:\n\nftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe\n",
            "subsections": []
        },
        "METHODS": {
            "content": "MAIN METHODS\n\"$captcha = Authen::Captcha->new();\"\nThis creates a new Captcha object. Optionally, you can pass in a hash with configuration\ninformation. See the method descriptions for more detail on what they mean.\n\ndatafolder => '/some/folder', # required\noutputfolder => '/some/http/folder', # required\nexpire => 300, # optional. default 300\nwidth =>  25, # optional. default 25\nheight => 35, # optional. default 35\nimagesfolder => '/some/folder', # optional. default to lib dir\nkeepfailures => 0, # optional, defaults to 0(false)\ndebug => 0, # optional. default 0\n\n\"$token = $captcha->generatecode( $numberofcharacters );\"\nCreates a captcha. Image filename is \"$token.png\"\n\nIt can also be called in array context to retrieve the string of characters used to generate\nthe captcha (the string the user is expected to respond with). This is useful for debugging.\nex.\n\n\"($token,$chars) = $captcha->generatecode( $numberofcharacters );\"\n\n\"$results = $captcha->checkcode($code,$token);\"\ncheck for a valid submitted captcha\n\n$code is the submitted letter combination guess from the user\n\n$token is the submitted token from the user (that we gave them)\n\nIf the $code and $token are correct, the image file and database entry will be removed.\n\nIf the $token matches one in the database, and \"keepfailures\" is false (the default), the\nimage file and database entry will be removed to avoid repeated attempts on the same\ncaptcha.\n\n$results will be one of:\n\n1 : Passed\n0 : Code not checked (file error)\n-1 : Failed: code expired\n-2 : Failed: invalid code (not in database)\n-3 : Failed: invalid code (code does not match token)\n\nACCESSOR METHODS\n\"$captcha->datafolder( '/some/folder' );\"\nRequired. Sets the directory to hold the flatfile database that will be used to store the\ncurrent non-expired valid captcha tokens. Must be writable by the process running the script\n(usually the web server user, which is usually either \"apache\" or \"http\"), but should not be\naccessible to the end user.\n\n\"$captcha->outputfolder( '/some/folder' );\"\nRequired. Sets the directory to hold the generated Captcha image files. This is usually a\nweb accessible directory so that the user can view the images in here, but it doesn't have\nto be web accessible (you could be attaching the images to an e-mail for some verification,\nor some other Captcha implementation). Must be writable by the process running the script\n(usually the web server user, which is usually either \"apache\" or \"http\").\n\n\"$captcha->imagesfolder( '/some/folder' );\"\nOptional, and may greatly affect the results... use with caution. Allows you to override the\ndefault character graphic png's and backgrounds with your own set of graphics. These are\nused in the generation of the final captcha image file. The defaults are held in: [lib\ninstall dir]/Authen/Captcha/images\n\n\"$captcha->expire( 300 );\"\nOptional. Sets the number of seconds this captcha will remain valid. This means that the\ncreated captcha's will not remain valid forever, just as long as you want them to be active.\nSet to an appropriate value for your application. Defaults to 300.\n\n\"$captcha->width( 25 );\"\nOptional. Number of pixels high for the character graphics. Defaults to 25.\n\n\"$captcha->height( 35 );\"\nOptional. Number of pixels wide for the character graphics. Defaults to 35.\n\n\"$captcha->keepfailures( [0|1] );\"\nOptional. Defaults to zero. This option controls whether or not the captcha will remain\nvalid after a failed attempt. By default, we only allow one attempt to solve it. This\ngreatly reduces the possibility that a bot could brute force a correct answer. Change it at\nyour own risk.\n\n\"$captcha->debug( [0|1|2] );\"\nOptional. Sets the debugging bit. 1 turns it on, 0 turns it off. 2 will print out verbose\nmessages to STDERR.\n",
            "subsections": []
        },
        "TODO": {
            "content": "sound file captcha: Incorporating distorted sound file creation.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "The Captcha project: http://www.captcha.net/\n\nThe origonal perl script this came from: http://www.firstproductions.com/cgi/\n",
            "subsections": []
        },
        "AUTHORS": {
            "content": "Seth T. Jackson, <sjackson@purifieddata.net>\n\nJosh I. Miller, <jmiller@purifieddata.net>\n\nFirst Productions, Inc. created the cgi-script distributed under the GPL which was used as the\nbasis for this module. Much work has gone into making this more robust, and suitable for other\napplications, but much of the origonal code remains.\n\nFixes were reported and contributed by various people, see Changes file for a complete list.\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "Copyright 2003, First Productions, Inc. (FIRSTPRODUCTIONS HUMAN TEST 1.0)\n\nCopyright 2003 by Seth Jackson\n\nCopyright 2012 by Paolo Rossi, Lubomir Rintel, Chris Dunlop, Gert Schepens and Ernesto\nHernández-Novich\n\nThis library is free software; you can redistribute it and/or modify it under the terms of the\nGNU General Public License as published by the Free Software Foundation; either version 2 of the\nLicense, or (at your option) any later version. (see license.txt).\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;\nwithout even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See\nthe GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program; if\nnot, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA\n02111-1307, USA\n",
            "subsections": []
        }
    },
    "summary": "Authen::Captcha - Perl extension for creating captcha's to verify the human element in transactions.",
    "flags": [],
    "examples": [],
    "see_also": []
}