====== CAPTCHA ======

---- plugin ----
description: This plugin provides a CAPTCHA field on subscription forms.
author     : Duncan Cameron
type       : 
compatible : 3.x
depends    : 
conflicts  : 
similar    : 
tags       : spam

sourcerepo : https://github.com/bramley/phplist-plugin-captcha

----

**Important** The Securimage package is no longer supported or recommended for use, see https://www.phpcaptcha.org/. If you want to use a captcha with phplist subscription forms then there are alternative phplist plugins

[[https://resources.phplist.com/plugin/recaptcha|reCAPTCHA V2 plugin]]

[[https://resources.phplist.com/plugin/recaptchav3|reCAPTCHA V3 plugin]]

[[https://resources.phplist.com/plugin/hCaptcha|hCaptcha plugin]]

[[https://resources.phplist.com/plugin/friendly-captcha|Friendly Captcha plugin]]


This plugin provides a CAPTCHA field on subscription forms using the [[https://www.phpcaptcha.org|Securimage]] package.

The CAPTCHA requires that the user type the letters and digits of a distorted image. Securimage 
also provides a refresh button to display an alternative image, and an audio button to play a sound recording of the characters.
{{:plugin:captcha_1.png?nolink&500|}}

The plugin can also check subscription emails for spam using the [[https://github.com/michield/botbouncer]] class. This currently uses only the Stop Forum Spam service to check email addresses, as that can be used without registering.
The other services supported by Botbouncer (Akismet, Project Honeypot, and Mollom) could be added if Stop Forum Spam proves not to be sufficient.

For another approach to captcha see the [[https://resources.phplist.com/plugin/recaptcha|reCAPTCHA plugin]].
====== Installation ======

See the README file on the GitHub page https://github.com/bramley/phplist-plugin-captcha

===== Change to the Securimage code =====

Starting in release 3.5.5 of phpList the php session is named 'phpListSession'.

Therefore if you are using phpList release 3.5.5 or later then you need to make a small change to the Securimage code so that it uses that session name.

In file securimage/securimage.php find this line. In release 3.6.7 of securimage it is line 487


<code php>    public $session_name   = null;</code>

then change it to 

<code php>    public $session_name   = 'phpListSession';</code>



====== Configuration ======

===== Settings =====

On the Settings page you can specify:

  * The path to the securimage directory on your web site (the default path is `/securimage`)
  * Whether to validate the email address using the BotBouncer class (the default is yes)
  * The prompt for the CAPTCHA field
  * The message to be displayed to the subscriber when the entered CAPTCHA is incorrect
  * The message to be displayed to the subscriber when the email address is rejected
  * Whether to write a record to the event log for each incorrect CAPTCHA and subscription attempt
  * Whether to send an email to the admin for each incorrect CAPTCHA and subscription attempt
{{:plugin:captcha_2.png?nolink&500|}}
===== Subscribe pages =====

For each subscribe page that you create you can select whether it should include a captcha field.
{{:plugin:captcha_3.png?nolink|}}
===== Customising the appearance of the captcha =====

The plugin does not support customising the appearance of the captcha widget. Instead you need to make minor modifications one of the Securimage files. See [[https://www.phpcaptcha.org/documentation/customizing-securimage/|this page]] of the Securimage documentation for more details.

===== Changing the number of characters displayed in the captcha =====

The captcha will display 6 characters by default. To alter this number you need to follow the guidance for customising the appearance of the captcha to modify the code_length property. For example to reduce the number of characters to 4:


  // display only 4 characters in the captcha
      $img->code_length = 4;


===== Internationalisation =====

If your subscribe pages are in a language other than English then on the Settings page you can change the prompt and messages that are displayed to the subscriber to be in the local language.

Securimage supports a limited number of languages for the audio playback.
See [[https://www.phpcaptcha.org/documentation/audio-file-settings/#language|Changing language files]] for how to change the language.

====== Test that it works ======

On your phplist subscription page enter all of the mandatory fields and an incorrect value in the CAPTCHA field.
The subscription attempt should be rejected.

Go to [[https://www.stopforumspam.com/stats#datatable|Stop Forum Spam]] and select an email address from the Last 500 Entries.
Then try to subscribe to your lists using that email address. 


====== Support ======
Report any issues or questions in the support forum https://discuss.phplist.org/