Captchas

General

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".

Usage

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 CAPTCHA_TEMPLATE -->
		<!-- INCLUDE {CAPTCHA_TEMPLATE} -->
		<!-- 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']);
    $captcha->init(CONFIRM_POST);

    // 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 ($vc_response)
        {
            $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
        
            $captcha->reset();
        }
        else if ($captcha->is_solved())
        {
            // 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
        $template->assign_vars(array(
            '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

Interface

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_solved()	Has the captcha been solved?				Bool	True if a valid solution was submitted.	function is_solved()
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::has_config()	Checks whether the captcha plugin has a config page				boolean	true iff the captcha has a config page	function has_config()
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()