Development Wiki


From phpBB Development Wiki

Revision as of 19:49, 6 August 2009 by Igorw (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):

		<!-- 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']);

// Put any errors messages that occur into the $error array
    // Of course this is only an example, you do not need to use this method of error handling
$error = array();
$s_hidden_fields '';
$submit request_var('submit'false);
// <Your code here>

if ($submit)
$vc_response $captcha->validate();
        if (
$error[] = $vc_response;

// <your code goes here:
        // validate form input and perform the actions (e.g. adding the user or posting the post)>
if (!sizeof($error))
// No errors => invalidate the question
            // IMPORTANT: Only do this when the action was really successful!
            //  -> otherwise the captcha would remain solved and a spammer
            //      could keep spamming without solving a CAPTCHA
        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 registered in the template later on
$s_hidden_fields .= build_hidden_fields($captcha->get_hidden_fields());

// if the form was not yet submitted or the CAPTCHA was not solved ...
if (!$submit || !$captcha->is_solved())
// ... display the CAPTCHA
'S_CONFIRM_CODE'                => true,
'CAPTCHA_TEMPLATE'              => $captcha->get_template(),

// <your code: display the form>

Naming Conventions

  • language files should use the name "captcha_<captcha name>.php
  • template files should use the name "captcha_<captcha name>.html
  • acp template files should use the name "captcha_<captcha name>_acp.html
  • demo template files should use the name "captcha_<captcha name>_acp_demo.html
  • plugin files have to use the name "phpbb_<captcha name>_plugin.php


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 $data Mixed The data array that corresponds to the type used on init. I.e. the user data(keys: username, email, tz, lang) for CONFIRM_REG and the post data (keys: username, subject, message) for CONFIRM_POST. Mixed false if the code was correct; a translated error string otherwise
function validate($data false)
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. false if the CAPTCHA should not be displayed (already solved etc).
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:uninstall() 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()