2010-06-10 04:31:06 +02:00
|
|
|
# SpamProtection Module
|
|
|
|
|
2022-07-05 09:07:16 +02:00
|
|
|
[![CI](https://github.com/silverstripe/silverstripe-spamprotection/actions/workflows/ci.yml/badge.svg)](https://github.com/silverstripe/silverstripe-spamprotection/actions/workflows/ci.yml)
|
2022-08-01 00:46:51 +02:00
|
|
|
[![Silverstripe supported module](https://img.shields.io/badge/silverstripe-supported-0071C4.svg)](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/)
|
2014-02-10 08:55:38 +01:00
|
|
|
|
2023-04-19 06:26:42 +02:00
|
|
|
## Installation
|
|
|
|
|
|
|
|
```sh
|
|
|
|
composer require silverstripe/spamprotection
|
|
|
|
```
|
|
|
|
|
2023-09-11 23:45:39 +02:00
|
|
|
## Maintainer Contact
|
|
|
|
|
|
|
|
* Saophalkun Ponlu
|
|
|
|
<phalkunz (at) silverstripe (dot) com>
|
|
|
|
|
|
|
|
* Will Rossiter
|
|
|
|
<will (at) fullscreen (dot) io>
|
|
|
|
|
2010-06-10 04:31:06 +02:00
|
|
|
## Documentation
|
|
|
|
|
2017-08-28 00:27:53 +02:00
|
|
|
This module provides a generic, consistent API for adding spam protection to
|
2022-08-01 00:46:51 +02:00
|
|
|
your Silverstripe Forms. This does not provide any spam protection out of the
|
2017-09-04 23:40:17 +02:00
|
|
|
box. For that, you must also download one of the spam protection
|
2014-02-10 08:53:59 +01:00
|
|
|
implementations. Currently available options are:
|
2010-06-10 04:31:06 +02:00
|
|
|
|
2018-04-05 08:09:30 +02:00
|
|
|
* reCAPTCHA v2 (two implementations: [one](https://github.com/chillu/silverstripe-recaptcha), [two](https://github.com/UndefinedOffset/silverstripe-nocaptcha))
|
2014-02-10 08:53:59 +01:00
|
|
|
* [MathSpamProtection](https://github.com/silverstripe/silverstripe-mathspamprotection)
|
2017-09-04 23:40:17 +02:00
|
|
|
* [Akismet](https://github.com/silverstripe/silverstripe-akismet)
|
|
|
|
* [Mollom](https://github.com/silverstripe-archive/silverstripe-mollom)
|
2023-07-11 03:36:10 +02:00
|
|
|
* [Cloudflare Turnstile](https://github.com/silverstripe-terraformers/turnstile-captcha/)
|
2010-06-10 04:31:06 +02:00
|
|
|
|
2014-02-10 08:53:59 +01:00
|
|
|
As a developer you can also provide your own protector by creating a class which
|
2017-09-04 23:40:17 +02:00
|
|
|
implements the `\SilverStripe\SpamProtection\SpamProtector` interface. More on that below.
|
2010-06-10 04:31:06 +02:00
|
|
|
|
2014-02-10 08:53:59 +01:00
|
|
|
## Configuring
|
2010-06-10 04:31:06 +02:00
|
|
|
|
2017-08-28 00:27:53 +02:00
|
|
|
After installing this module and a protector of your choice (i.e mollom) you'll
|
|
|
|
need to rebuild your database through `dev/build` and set the default protector
|
2014-02-10 08:53:59 +01:00
|
|
|
via SilverStripe's config system. This will update any Form instances that have
|
|
|
|
spam protection hooks with that protector.
|
|
|
|
|
2023-09-11 23:45:39 +02:00
|
|
|
*mysite/_config/spamprotection.yml*
|
2014-02-10 08:53:59 +01:00
|
|
|
|
2017-08-28 00:57:30 +02:00
|
|
|
```yaml
|
|
|
|
---
|
2017-12-19 03:36:59 +01:00
|
|
|
name: mycustomspamprotection
|
2017-08-28 00:57:30 +02:00
|
|
|
---
|
|
|
|
SilverStripe\SpamProtection\Extension\FormSpamProtectionExtension:
|
|
|
|
default_spam_protector: MollomSpamProtector
|
|
|
|
```
|
2014-02-10 08:53:59 +01:00
|
|
|
|
|
|
|
To add spam protection to your form instance call `enableSpamProtection`.
|
2017-08-28 00:27:53 +02:00
|
|
|
|
2017-08-28 00:57:30 +02:00
|
|
|
```php
|
|
|
|
// your existing form code
|
|
|
|
$form = new Form(/* .. */);
|
|
|
|
$form->enableSpamProtection();
|
|
|
|
```
|
2014-02-10 08:53:59 +01:00
|
|
|
|
2017-08-28 00:27:53 +02:00
|
|
|
The logic to perform the actual spam validation is controlled by each of the
|
2017-09-04 23:40:17 +02:00
|
|
|
individual `SpamProtector` implementations since they each require a different
|
2014-02-10 08:53:59 +01:00
|
|
|
implementation client side or server side.
|
|
|
|
|
|
|
|
### Options
|
|
|
|
|
2017-08-28 00:27:53 +02:00
|
|
|
`enableSpamProtection` takes a hash of optional configuration values.
|
2014-02-10 08:53:59 +01:00
|
|
|
|
2017-08-28 00:57:30 +02:00
|
|
|
```php
|
2023-09-11 23:45:39 +02:00
|
|
|
$form->enableSpamProtection(array(
|
2017-08-28 00:57:30 +02:00
|
|
|
'protector' => MathSpamProtector::class,
|
|
|
|
'name' => 'Captcha'
|
2023-09-11 23:45:39 +02:00
|
|
|
));
|
2017-08-28 00:57:30 +02:00
|
|
|
```
|
2014-02-10 08:53:59 +01:00
|
|
|
|
|
|
|
Options to configure are:
|
|
|
|
|
2017-09-04 23:40:17 +02:00
|
|
|
* `protector`: a class name string or class instance which implements
|
|
|
|
`\SilverStripe\SpamProtection\SpamProtector`. Defaults to your
|
|
|
|
`SilverStripe\SpamProtection\Extension\FormSpamProtectionExtension.default_spam_protector` value.
|
2014-02-10 08:53:59 +01:00
|
|
|
|
2017-09-04 23:40:17 +02:00
|
|
|
* `name`: the form field name argument for the Captcha. Defaults to `Captcha`.
|
|
|
|
* `title`: title of the Captcha form field. Defaults to `''`
|
|
|
|
* `insertBefore`: name of existing field to insert the spam protection field prior to
|
|
|
|
* `mapping`: an array mapping of the Form fields to the standardised list of
|
|
|
|
field names. The list of standardised fields to pass to the spam protector are:
|
2014-02-10 08:53:59 +01:00
|
|
|
|
2017-08-28 00:57:30 +02:00
|
|
|
```
|
|
|
|
title
|
|
|
|
body
|
|
|
|
contextUrl
|
|
|
|
contextTitle
|
|
|
|
authorName
|
|
|
|
authorMail
|
|
|
|
authorUrl
|
|
|
|
authorIp
|
|
|
|
authorId
|
|
|
|
```
|
2014-02-10 08:53:59 +01:00
|
|
|
|
|
|
|
## Defining your own `SpamProtector`
|
|
|
|
|
2017-09-04 23:40:17 +02:00
|
|
|
Any class that implements `\SilverStripe\SpamProtection\SpamProtector` and the `getFormField()` method can
|
2017-08-28 00:27:53 +02:00
|
|
|
be set as the spam protector. The `getFormField()` method returns the
|
2014-02-10 08:53:59 +01:00
|
|
|
`FormField` to be inserted into the `Form`. The `FormField` returned should be
|
|
|
|
in charge of the validation process.
|
|
|
|
|
2017-08-28 03:44:53 +02:00
|
|
|
```php
|
2017-08-28 00:57:30 +02:00
|
|
|
<?php
|
2014-02-10 08:53:59 +01:00
|
|
|
|
2017-08-28 00:57:30 +02:00
|
|
|
use CaptchaField;
|
|
|
|
use SilverStripe\SpamProtection\SpamProtector;
|
2014-02-10 08:53:59 +01:00
|
|
|
|
2017-08-28 00:57:30 +02:00
|
|
|
class CustomSpamProtector implements SpamProtector
|
|
|
|
{
|
|
|
|
public function getFormField($name = null, $title = null, $value = null)
|
|
|
|
{
|
|
|
|
// CaptchaField is an imagined class which has some functionality.
|
|
|
|
// See silverstripe-mollom module for an example.
|
|
|
|
return new CaptchaField($name, $title, $value);
|
2014-02-10 08:53:59 +01:00
|
|
|
}
|
2017-08-28 00:57:30 +02:00
|
|
|
}
|
|
|
|
```
|
2014-02-10 08:53:59 +01:00
|
|
|
|
|
|
|
## Using Spam Protection with User Forms
|
|
|
|
|
2017-08-28 00:57:30 +02:00
|
|
|
This module provides an `EditableSpamProtectionField` wrapper which you can add
|
|
|
|
to your UserForm instances. After installing this module and running `/dev/build`
|
2017-08-28 00:27:53 +02:00
|
|
|
to rebuild the database, your Form Builder interface will have an option for
|
|
|
|
`Spam Protection Field`. The type of spam protection used will be based on your
|
2014-02-10 08:53:59 +01:00
|
|
|
currently selected SpamProtector instance.
|
|
|
|
|
|
|
|
## Releasing code with Spam Protection support
|
|
|
|
|
2017-08-28 00:27:53 +02:00
|
|
|
Spam protection is useful to provide but in some cases we do not want to require
|
|
|
|
the developer to use spam protection. In that case, modules can provide the
|
2017-09-04 23:40:17 +02:00
|
|
|
following pattern:
|
2014-02-10 08:53:59 +01:00
|
|
|
|
2017-08-28 00:57:30 +02:00
|
|
|
```php
|
|
|
|
use SilverStripe\Forms\Form;
|
|
|
|
use SilverStripe\SpamProtection\Extension\FormSpamProtectionExtension;
|
2014-02-10 08:53:59 +01:00
|
|
|
|
2017-08-28 00:57:30 +02:00
|
|
|
$form = new Form(/* .. */);
|
|
|
|
|
|
|
|
if ($form->hasExtension(FormSpamProtectionExtension::class)) {
|
|
|
|
$form->enableSpamProtection();
|
|
|
|
}
|
|
|
|
```
|