Honeypot for Spam Protection

Relevant source files

The following files were used as context for generating this wiki page:

• source/libraries/honeypot.rst
• source/incoming/filters.rst
• source/helpers/form_helper.rst
• source/general/configuration.rst
• source/changelogs/v4.0.0-rc.3.rst

The Honeypot library provides a simple yet effective method for protecting forms from spam bots. It works by creating a hidden form field that should not be filled in by human users. Most bots will automatically fill in all fields, including the hidden "honeypot" field. The system detects when this field has a value and flags the submission as spam, preventing it from being processed. This protection is implemented as a Controller Filter and is integrated with the Form Helper.

This feature offers a non-intrusive alternative to CAPTCHAs, improving the user experience while providing a first line of defense against automated spam. It is easily configurable and can be applied globally to all POST requests or to specific routes. When a bot is detected, the system throws a CodeIgniter\Honeypot\Exceptions\HoneypotException.

Sources: source/libraries/honeypot.rst, source/incoming/filters.rst

Configuration

The Honeypot feature is configured through the app/Config/Honeypot.php file. If this file does not exist, you can create it by copying vendor/codeigniter4/framework/src/Config/Honeypot.php into your app/Config directory. All configuration options are stored as public properties within this class.

Sources: source/libraries/honeypot.rst:22-26, source/general/configuration.rst

Configuration Options

The following table details the available configuration options in the Config\Honeypot class.

Property	Type	Default Value	Description
$hidden	boolean	true	Determines if the honeypot field should be hidden with inline CSS. Set to false for testing.
$label	string	'Fill This Field'	The text for the <label> that accompanies the honeypot field.
$name	string	'honeypot'	The name attribute of the honeypot form input.
$template	string	'<label>{label}</label><input type="text" name="{name}" value="">'	The HTML template used to render the honeypot field. {label} and {name} are placeholders.
$container	string	'<div style="display:none">{template}</div>'	An HTML container that wraps the template. Used to ensure the field is not visible to users.

Sources: source/libraries/honeypot.rst:31-48

Enabling Honeypot Protection

To activate the Honeypot, you must enable it as a controller filter. This is done in the app/Config/Filters.php file.

Sources: source/libraries/honeypot.rst:53-54, source/incoming/filters.rst

Applying the Filter

You can apply the honeypot filter either globally to all POST requests or to specific routes.

1. Global Application: To protect all POST requests on your site, add the honeypot filter to the $globals property in app/Config/Filters.php.

   // In app/Config/Filters.php
   public array $globals = [
       'before' => [
           // 'honeypot',
           // 'csrf',
       ],
       'after' => [
           'toolbar',
           // 'honeypot',
       ],
   ];
   

   To enable it, uncomment the 'honeypot' line in the before array.

2. Route-Specific Application: To apply the filter only to certain routes, add it to the $filters property of a route definition in app/Config/Routes.php.

   // In app/Config/Routes.php
   $routes->post('contact', 'Contact::attemptSend', ['filter' => 'honeypot']);
   

Sources: source/libraries/honeypot.rst:56-78, source/incoming/filters.rst:71-89

Adding the Honeypot to Forms

Once the filter is enabled, you must add the honeypot field to your HTML forms. This can be done automatically using the Form Helper or manually.

Using the Form Helper

If you use the form_open() function from the Form Helper, the honeypot field is automatically inserted for you. The helper checks if the honeypot filter is enabled for the current route and adds the field if necessary.

<?= form_open() ?>
    // ... your form fields
<?= form_close() ?>

Sources: source/libraries/honeypot.rst:83-87, source/helpers/form_helper.rst

Manual Insertion

If you are not using form_open(), you can use the honeypot_field() helper function to insert the field manually. This function returns the HTML for the honeypot field based on your configuration.

<form action="..." method="post">
    <?= honeypot_field() ?>
    // ... your form fields
</form>

Sources: source/libraries/honeypot.rst:89-94, source/helpers/form_helper.rst

Request Processing Flow

The following diagram illustrates how the Honeypot filter processes an incoming POST request.

This diagram shows that the Honeypot filter acts as a gatekeeper. If the hidden honeypot field in a POST request contains any data, the filter assumes it's a bot and throws an exception, halting further execution. If the field is empty, the request is allowed to proceed to the designated controller.

Sources: source/libraries/honeypot.rst:1-10, 53-65, source/incoming/filters.rst

Sequence of Events

This sequence diagram details the interaction between the user, the CodeIgniter framework, and the Honeypot filter during a form submission.

This diagram shows the before() method of the HoneypotFilter being called by the framework. The filter inspects the request data. If the submission is deemed spam, an exception is thrown. Otherwise, control is passed back to the framework, which then invokes the appropriate controller method.

Sources: source/libraries/honeypot.rst:100-106, source/incoming/filters.rst:27-36

Conclusion

The Honeypot library is a lightweight, user-friendly tool for spam mitigation in CodeIgniter 4. By leveraging a hidden form field and a controller filter, it effectively blocks many simple spam bots without requiring user interaction like a CAPTCHA. Its seamless integration with the Form Helper and flexible configuration make it an easy-to-implement first layer of defense for any web application form.

Sources: source/libraries/honeypot.rst, source/changelogs/v4.0.0-rc.3.rst:39