# PHP Form Spam Checker 2.1
**A layered, dependency-free anti-spam pipeline and HTTP firewall for any PHP
form.** It runs local heuristics first, then behavioural signals, IP reputation,
DNS blocklists, mail-domain authentication and a Bayesian classifier — and
optionally inspects the whole HTTP request with a WAF. No captcha, no runtime
Composer dependencies, and every verdict carries evidence: which checks fired,
with which scores, and why.
[](https://github.com/paulmann/PHP-Form-Spam-Checker/actions/workflows/ci.yml)
[](https://github.com/paulmann/PHP-Form-Spam-Checker/releases)
[](https://php.net/)
[](LICENSE)
[**Wiki**](https://github.com/paulmann/PHP-Form-Spam-Checker/wiki) · [**Docs**](https://github.com/paulmann/PHP-Form-Spam-Checker/tree/main/docs) · [**Releases**](https://github.com/paulmann/PHP-Form-Spam-Checker/releases) · [**Changelog**](CHANGELOG.md) · [**Issues**](https://github.com/paulmann/PHP-Form-Spam-Checker/issues) · [**Security**](SECURITY.md) · [**For agents**](AGENTS.md) · [**Русская версия**](README.ru.md)
> **Documentation status.** The counts in this README were measured from the
> repository tree on 2026-11-03 (version 2.1.0); the command that produced each
> figure is named beside it. Long-form guides live in the
> [Wiki](https://github.com/paulmann/PHP-Form-Spam-Checker/wiki) and in `docs/`;
> the non-interactive contract for agents is [`AGENTS.md`](AGENTS.md).
---
## Contents
- [What changed in 2.1.2](#what-changed-in-212)
- [What changed in 2.1](#what-changed-in-21)
- [What changed in 2.0](#what-changed-in-20)
- [The protection cycle](#the-protection-cycle)
- [Check modules and defaults](#check-modules-and-defaults)
- [By the numbers](#by-the-numbers)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start: plain PHP form](#quick-start-plain-php-form)
- [WAF (HTTP firewall)](#waf-http-firewall)
- [AbuseIPDB setup](#abuseipdb-setup)
- [Fail2Ban and auto-ban](#fail2ban-and-auto-ban)
- [DNSBL, SPF, DMARC, DKIM](#dnsbl-spf-dmarc-dkim)
- [Bayesian classifier](#bayesian-classifier)
- [Behavioural layer](#behavioural-layer)
- [Integration modes](#integration-modes)
- [Configuration quick reference](#configuration-quick-reference)
- [Quality gates](#quality-gates)
- [Testing](#testing)
- [Migration and compatibility](#migration-and-compatibility)
- [Security](#security)
- [Documentation index](#documentation-index)
- [Help the project — through evidence, not engagement](#help-the-project--through-evidence-not-engagement)
- [License](#license)
---
## What changed in 2.1.2
2.1.2 adds a locale check for Russian-language forms and turns it on in the
reference deployment configs:
- **Cyrillic requirement for names** (`language.require_cyrillic`): the
configured name-like fields (`name`, `fio`, `first_name`, `last_name`,
`surname`, `имя`, `фамилия`, `фио`, …; matched case- and
separator-insensitively) must contain at least one Cyrillic letter. A value
that has letters but no Cyrillic adds `language.missing_score` points —
`40` by default, `60` in the reference deployment configs, where a Latin-only
name alone reaches the spam threshold; `missing_score = 40` downgrades it to
"suspicious". E-mail, company and free-text fields are never checked, and
`language.fields` / `min_letters` / `max_score` tune the rule.
- The shared-server configs in `config/sites/` enable the rule on every site.
See [CHANGELOG.md](CHANGELOG.md) and the `language.*` keys in
[docs/CONFIG.md](docs/CONFIG.md).
## What changed in 2.1
2.1 adds the firewall bridge and the deployment hardening on top of 2.0:
- **AbuseIPDB** with `threshold = 100` in the reference deployment configs
(only IPs whose confidence is exactly 100 are blocked); cached 6 h, fail open,
circuit breaker, quota surfaced in the evidence.
- **Fail2Ban bridge** — every hard-spam verdict and every WAF block appends a
timestamped `PHPFSC BAN ip=…` line to a per-site log; the jail bans the IP on
the firewall (HTTP/HTTPS only) with `maxretry = 1`.
- **Application auto-ban** — `autoban` check: after N hard events inside a
window the IP is rejected before any other check for the configured TTL.
- `CurlClient` no longer uses the deprecated `curl_close()` (PHP 8.5).
See [CHANGELOG.md](CHANGELOG.md) and [docs/WAF.md#fail2ban](docs/WAF.md#fail2ban).
## What changed in 2.0
2.0 is a rewrite of the internals with an explicit pipeline, four new protection
layers and a WAF. The integration surface that deployed 1.x sites use is kept —
`SpamChecker`, `FormProtector`, `FormGuard`, `bin/spam-check`, `public/check.php`
and `config/sites/.php` keep their contracts. Upgrading is configuration,
not code, for most installations.
| | 1.x | 2.0 |
|---|---|---|
| Pipeline | one checker aggregating 12 checks | ordered `SpamPipeline`, early exit on hard spam |
| Behavioural | static honeypot + time trap | + **dynamic honeypot** (hourly HMAC names) and **JS challenge** |
| Network | none | **AbuseIPDB**, **DNSBL** (opt-in, fail open) |
| Mail domains | syntactic e-mail check | + **SPF**, **DMARC** domain trust signals |
| Machine learning | none | **Bayesian classifier** with `bin/spam-train` |
| HTTP firewall | none | **WAF**: 9 rules, `off`/`monitor`/`block`, drop-in `auto_prepend` |
| Evidence | reason list | per-check `status`, `score`, `reason`, structured `evidence` |
| CLI | `bin/spam-check` | + `bin/waf-check`, + `bin/spam-train` |
| Quality gates | PHPUnit + `php -l` | CS Fixer, PHPStan `max`, Psalm taint, coverage gate, CI |
Full details and the breaking changes (removed internal classes, per-check
status vocabulary): [docs/MIGRATION-1-to-2.md](docs/MIGRATION-1-to-2.md).
## The protection cycle
```mermaid
flowchart TD
A[HTTP request] --> B{WAF enabled?}
B -- yes --> C[WAF rules: method, URI,
query, fields, cookies,
headers, body]
C -- blocked --> Z[403 / monitor: log only]
C -- pass --> D[Form submission]
B -- no --> D
D --> E[Behavioural:
dynamic honeypot · time trap · JS challenge]
E --> F[Local heuristics:
UA · rate limit · length · SQLi ·
XSS · links · keywords · email ·
repetition · language]
F --> G[Network reputation:
AbuseIPDB · DNSBL]
G --> H[Mail-domain authentication:
SPF · DMARC]
H --> I[Bayesian classifier]
I --> J[Aggregate: hard verdicts +
capped score vs thresholds]
J --> K{Clean / Suspicious / Spam}
```
Cheap checks run first. `pipeline.stop_on_spam` (default `true`) stops the run on
the first hard spam verdict, which saves AbuseIPDB quota and DNS lookups. A
check that throws is recorded as `error` and fails open.
## Check modules and defaults
All scores are 0–100; `spam` is a hard verdict that ignores the total.
| Layer | Check | Default | Score / effect |
|---|---|---|---|
| Behaviour | `honeypot` | on | filled hidden field → **spam** 100 |
| Behaviour | `dynamic_honeypot` | on when a ≥16-char secret is set | filled → **spam** 100; neither expected field posted → 10 |
| Behaviour | `time_trap` | off (needs a rendered secret) | too fast / forged → spam 80; missing / expired → 30 |
| Behaviour | `js_challenge` | off | missing/invalid answer → 15 (never hard) |
| Identity | `user_agent` | on | empty UA → 40; tool/marker UA → **spam** 100 |
| Volume | `rate_limit` | on, 8 / 900 s | exceeded → **spam** 100 |
| Firewall | `autoban` | off (reference deployments: on) | banned IP → **spam** 100, before any other check |
| Payload | `length` | on, max 5000 | long → 30; > 20000 or control chars → **spam** 100 |
| Injection | `sql_injection` | on | strong signature → **spam** 100; weak → 40 |
| Injection | `xss` | on | script/handler → **spam** 100; encoded → 45 |
| Content | `links` | on, max 2 | extra link 15; shortener 35; obfuscated 25 |
| Content | `keywords` | on | 12 per hit, max 90 |
| Contact | `email` | on | invalid 40; disposable 70 |
| Content | `repetition` | on | runs/repeats → 25, max 60 |
| Content | `language` | off (reference deployments: on) | mixed scripts → 20, max 40; `require_cyrillic` → Latin-only name 60 (spam) |
| Network | `abuseipdb` | off | confidence ≥ 90 → **spam** (score = confidence) |
| Network | `dnsbl` | off | listing → **spam** 100 |
| Domain | `spf` | off | no usable policy → 10 |
| Domain | `dmarc` | off | missing → 10; `p=none` → 5 |
| Model | `bayes` | off | `P(spam) ≥ 0.92` → score = `P × 100` (suspicious by default) |
`dkim` configuration is reserved for a later check and is not in the pipeline
yet — see [docs/CHECKS.md](docs/CHECKS.md#dkim).
## By the numbers
Measured from the repository tree on 2026-11-03 at commit `eed037b`; each figure
names the command that produced it.
| Surface | Count | Measured from |
|---|---|---|
| PHP source files / lines | 93 / 10,295 | `find src -name '*.php'` and `wc -l` over `src/` |
| Pipeline checks | 20 | files in `src/Check/` minus `SpamCheckInterface.php` |
| WAF rules | 9 | files in `src/Waf/Rules/` |
| Test methods | 555 | `public function test` declarations under `tests/` |
| Test suite | 559 tests / 2,015 assertions | `php vendor/bin/phpunit` on 2026-11-03 (PHPUnit 13.4.5) |
| English documentation pages | 6 | `docs/*.md` excluding `*.ru.md` |
| Runtime Composer dependencies | 0 | `require` in `composer.json` (PHP extensions only) |
| Supported PHP | 8.5+ | `require.php` in `composer.json`; CI matrix `8.5.12` and `8.5` |
## Requirements
- PHP **8.5** (`>=8.5`; CI runs 8.5.12 and 8.5)
- `ext-mbstring`, `ext-json`; `ext-curl` only when the bundled HTTP client is
used (AbuseIPDB)
- No runtime Composer dependencies
## Installation
### Composer
```bash
composer require paulmann/php-form-spam-checker
```
### Plain copy
Copy the repository somewhere readable by PHP and include `autoload.php`:
```php
require '/var/www/lib/PHP-Form-Spam-Checker/autoload.php';
```
The bundled `autoload.php` works with and without `vendor/`.
## Quick start: plain PHP form
```php
verify($_POST, 'contact', Context::fromGlobals());
if ($verdict->isSpam()) {
http_response_code(400);
exit('Заявка отклонена антиспам-проверкой.');
}
// ... send the e-mail
}
?>
```
Run the demo: `php -S 127.0.0.1:8080 examples/plain-form.php`
([examples/plain-form.php](examples/plain-form.php)).
## WAF (HTTP firewall)
The WAF inspects every HTTP request before the application: method, URI, query,
form fields, cookies, headers and the raw body. It is **off by default**.
| Mode | Behaviour |
|---|---|
| `off` | nothing is inspected |
| `monitor` | verdict is computed and logged; every request passes |
| `block` | a blocked request is answered (`403` by default, `X-WAF: blocked`) |
```php
// config/spam.php
'waf' => [
'enabled' => true,
'mode' => 'monitor', // start here, switch to block after review
'block_status' => 403,
'max_body_bytes' => 1048576,
'rules' => [
'sql_injection' => true,
'xss' => true,
'path_traversal' => true,
'command_injection' => true,
'scanner' => true,
'header_injection' => true,
'protocol' => true,
'ip_reputation' => false, // needs an injected reputation check
'rate_limit' => false, // needs injected storage
],
],
```
Install as a drop-in. Pick the include that matches the site — `guard.php`
already runs the WAF first when `waf.enabled` is set, so do not load both:
```php
// site with a form guard: WAF first, then the form pipeline
require '/var/www/lib/PHP-Form-Spam-Checker/integrations/guard.php';
// site without a form guard: firewall only
require '/var/www/lib/PHP-Form-Spam-Checker/integrations/waf.php';
```
…or globally for a PHP-FPM pool:
```ini
; firewall only
php_admin_value[auto_prepend_file] = /var/www/lib/PHP-Form-Spam-Checker/integrations/waf.php
```
On a pool that also uses the form guard, point `auto_prepend_file` at
`integrations/auto-prepend.php` instead: it runs the WAF layer independently of
the legacy `auto` flag and gates the form pipeline with that flag.
Per-site configuration is the same `config/sites/.php` file the form
guard uses (`waf` section inside `config`, optional top-level `waf_mode`,
`waf_skip`, `waf_match`, `waf_response`). The default skip list protects
`/admin`, `/login`, `/auth`, `/wp-admin`, `/bitrix/admin`, `/cpanel`; an
explicit `waf_skip` replaces it. Response codes and bodies: `403` + JSON for
`Accept: application/json` or `/api` URIs, HTML otherwise, `silent` = HTTP 200
with an empty body.
For non-PHP back ends: `bin/waf-check` (`0` allow, `2` block, `3` error).
Full guide: [docs/WAF.md](docs/WAF.md).
## AbuseIPDB setup
1. Create a key at → *API*.
2. Export it, never commit it:
```bash
export ABUSEIPDB_KEY='…'
```
3. Reference the environment variable in the configuration:
```php
'abuseipdb' => [
'enabled' => true,
'api_key' => getenv('ABUSEIPDB_KEY') ?: '',
'threshold' => 90, // abuseConfidenceScore that becomes hard spam
'cache_ttl' => 21600, // 6 h per-IP cache: a burst costs one query
'timeout' => 2.0,
'max_age_days' => 30, // reports newer than 30 days
'fail_open' => true, // lookup failure contributes nothing
'circuit_breaker' => ['failures' => 3, 'cooldown' => 300],
],
```
Behaviour: private/loopback addresses and missing keys never trigger a network
call (`uncertain`); a score on or above `threshold` is a hard spam verdict with
the confidence as its score; `HTTP 429` stores `Retry-After` and backs off
without retrying; three consecutive transport/`5xx` failures open the circuit
breaker for 5 minutes; the first successful HTTP response closes it. The client
IP is sent to AbuseIPDB — see [SECURITY.md](SECURITY.md#network-egress).
Runnable wiring example: [examples/abuseipdb.php](examples/abuseipdb.php).
## Fail2Ban and auto-ban
Hard-spam verdicts and WAF blocks can be handed to the firewall:
- `fail2ban.enabled` appends one line per event to `fail2ban.log_path`:
`PHPFSC BAN ip= site= form=