Development Wiki


From phpBB Development Wiki

Revision as of 16:47, 18 June 2009 by Toonarmy (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:

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

In php, the corresponding code would look like this:

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

$error[] = $vc_response;
$captcha_solved false;

$captcha_solved true;
// store the entered code in a hidden field, so that users don't have to enter the captcha twice
$s_hidden_fields .= build_hidden_fields($captcha->get_hidden_fields());
// ... do something

        // invalidate the question (if there were no errors)
        // 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
if (!sizeof($error))
    if (!
'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. $type Int the type as defined in constants.php 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()
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. 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()