Development Wiki


From phpBB Development Wiki

Revision as of 16:40, 28 June 2009 by Kellanved (Talk | contribs)


The CAPTCHA plugin system is designed to allow any kind of anti-BOT without having to edit files. The CAPTCHA infrastructure of 3.0.5 was refactored into captcha_abstract.php. As a naming convention, all CAPTCHA plugins have to end with "_plugin.php" and begin with the CAPTCHA's class name. I.e. a CAPTCHA class named "phpbb_captcha_gd" has to be defined in a file named "phpbb_captcha_gd_plugin.php".


The use of the captcha plugins is closely related to the old system. On the style side, a typical example would be (plus the actual form around it):

		<!-- IF S_CONFIRM_CODE -->
		<!-- ENDIF -->

In php, the corresponding code would look like this. (the code does not include the parts where the actual form gets processed. It is just the part of an hypothetical page that deals with CAPTCHAs:

// Get the captcha instance
include($phpbb_root_path 'includes/captcha/captcha_factory.' $phpEx);
$captcha =& phpbb_captcha_factory::get_instance($config['captcha_plugin']);

// We assume that all errors in the form processing get added to the $error array; for instance taken usernames
    // , mismatching passwords. You can use other ways of error handling. 
$error = array();
$submit request_var('submit'false);
// ...
if ($submit)
$vc_response $captcha->validate();
        if (

$error[] = $vc_response;
// actual form handling code
        // do your thing, validate other input
        // ... 
if (!sizeof($error))
// everything went fine,perform the actions like adding the user, posting the post ...
            // invalidate the question if (and only if) the form is without errors and will get processed
            // this is important, as otherwise the captcha would remain solved
            // a spammer could solve it once and then use the answer until the session expires
        else if (
// okay, captcha solved, but something else went wrong.
            // store the entered code in a hidden field, so that users don't have to enter the captcha twice
            // assumes that $s_hidden_fields is forwarded to the template
$s_hidden_fields .= build_hidden_fields($captcha->get_hidden_fields());

    if (!
$submit || !$captcha->is_solved())
'S_CONFIRM_CODE'                => true,
'CAPTCHA_TEMPLATE'              => $captcha->get_template(),


Name Description Parameters Return Signature
Name Type Description Type Description
Captcha Plugin Validation
captcha_plugin::init() Initiates the CAPTCHA to validate codes, called after instantiation. Note that the default plugins only allow one CAPTCHA of any given type at the same time per session. $type Int the type as defined in constants.php (e.g. CONFIRM_REG) Void
function init($type)
captcha_plugin::validate() Checks the captcha Mixed false if the code was correct; a translated error string otherwise
function validate()
captcha_plugin::reset() Resets the captcha Void
function reset()
captcha_plugin::get_attempt_count() Returns the failure count. Integer Failed attempts by the current user
function get_attempt_count()
captcha_plugin::is_valid() Has the captcha been solved? Bool True iff a valid solution was submitted.
function is_valid()
Display Methods
captcha_plugin::get_template() Assigns all template variables required for the CAPTCHA. Returns the template filename to embed the captcha in another template. Should be called after validate(). String The filename of the file containing the template to display the CAPTCHA.
function get_template()
captcha_plugin::execute() Delivers the image of image based captchas; not required for text/remote etc CAPTCHAs. Void
function execute()
captcha_plugin::get_hidden_fields() Returns the data needed to preserve the captcha state so that users do not have to solve the CAPTCHA twice. Mixed A String => String Array, which gets embedded into the page as hidden fields
function get_hidden_fields()
System Methods
captcha_plugin::garbage_collect() Static; Clears leftover entries in the database; called in CRON. Void
static function garbage_collect()
captcha_plugin::get_name() Static; Returns the name corresponding to a language Key String A language Key for display in the ACP
static function get_name
captcha_plugin::get_class_name() Static; Returns the class name for instantiating the captcha. NOTE: this has to correspond to the file name. String The class name to instantiate the CAPTCHA.
static function get_class_name()
captcha_plugin::get_instance() Static; Factory Method. Returns a reference to an instance; does not have to be the same instance twice (but can be singleton). Mixed An instance of the CAPTCHA class.
static function &get_instance()
captcha_plugin::is_available() Static; Checks whether the captcha plugin can be used boolean true iff the captcha will work on the current install
static function is_available()
captcha_plugin:install() Called when the plugin is selected in the ACP. Void
function install()
captcha_plugin:install() Called when the plugin was selected in the ACP and another plugin is chosen. Void
function uninstall()
ACP Pages
captcha_plugin::acp_page() Displays the configuration options in the ACP. id Integer Module identifier for the acp captcha module. Void
function acp_page($id, &$module)
module Mixed Reference to surrounding acp_captcha module instance
captcha_plugin::get_demo_template() Returns the template filename and assigns variables. String The filename to include a demo of this CAPTCHA.
function get_demo_template()
captcha_plugin::execute_demo() Delivers a demo image of image based captchas; not required for text/remote etc CAPTCHAs. Void
function execute_demo()