feat: add a public spam check API for third-party integrations

[2ndkauboy]

Closes #507.

Adds a documented, stable entry point for plugins that want their own content checked, so AntispamBee\Handlers\Rules can stay internal.

The trigger was the first real-world integration, epiphyt/form-block on its antispam-bee branch. Reviewing it surfaced three things worth settling before writing documentation, because the docs freeze whatever we describe.

1. new Rules( $reaction_type ) was the only way in

Rules is an internal handler that Reaction::process() instantiates. Documenting it would have made its constructor permanent third-party API.

AntispamBee\Api\SpamCheck is now the entry point, and Handlers\Rules and Handlers\PostProcessors are marked @internal:

$result = \AntispamBee\Api\SpamCheck::check(
    [ 'author' => $name, 'body' => $message, 'email' => $email ],
    'my_plugin_form'
);

if ( $result->is_spam() ) {
    $reasons = $result->get_reasons();
}

CheckResult carries the verdict, the reason slugs and the payload. It is an object rather than a boolean mainly because of was_evaluated(): a result can report "no spam" simply because no rule was active, and that is the most common reason an integration appears to do nothing. has_active_rules() lets an integration warn an administrator before any submission arrives, and get_reason_texts() resolves stored slugs so integrators need a single import.

2. The payload contract was easy to get wrong

form-block hand-built the item and left host empty. RegexpSpam reads host separately from rawurl, so a good number of our own patterns could never match. Nobody should have to know that host is wp_parse_url( $url, PHP_URL_HOST ).

SpamCheck::check() normalizes: it derives host from url via DataHelper::parse_url() and defaults ip and useragent from the current request, so a form plugin passes only what it actually has. The new antispam_bee_api_payload filter is the escape hatch.

3. Nothing was checked until an administrator ticked a box

Settings::$defaults only covered comment, linkback and general, so every ControllableBase rule started inactive for a reaction type registered by another plugin — including rules the integration had explicitly opted in. Verified on a local install: form-block's integration worked, but only because its settings tab had been visited and BBCode ticked. rule_asb_regexp_active was still unset there, so RegexpSpam silently never ran.

Settings::get_defaults() applies a new antispam_bee_default_options filter, and get_options() fills in the defaults of reaction types absent from the stored options.

Defaults deliberately apply only to reaction types that were never saved. An unticked checkbox is removed from the stored options by Sanitize::sanitize_controllables(), so merging defaults underneath the stored state would re-enable a rule an administrator had deliberately disabled — for comment and linkback too. There is a unit test for exactly this.

Rules::apply() now logs when no rule is active, so the "nothing ran" case leaves a trace instead of silently reporting no spam.

Also: comment-only post-processors

SaveReason and SendEmail defer their work to comment_post. For an item that never becomes a comment the callback not only never runs, it stays attached for the rest of the request — so an unrelated comment inserted later would be stamped with that item's spam reasons, or trigger its notification email. Both now bail unless comment_post_ID is set, mirroring what UpdateSpamLog::process() already does.

The check is structural on purpose: comment_type is legitimately empty for a regular comment, and gating on reaction_type would only re-block what an integration explicitly opted in via antispam_bee_post_processor_supported_types.

Documentation

New docs/integrating-own-content.md covers the API, the payload attributes, registering a custom reaction type, and registering your own post-processor via antispam_bee_post_processors (already supported, previously undocumented). Two traps are called out explicitly:

• Rules register during module initialization, which is skipped for Ajax requests, so a plugin submitting over Ajax must allow it via antispam_bee_disallow_ajax_calls and register that filter early. REST requests are unaffected, because wp_doing_ajax() is false for them.
• Our own post-processors support comments and linkbacks by design: they write comment meta, build notifications from a stored comment, and feed a spam counter rendered next to the comment counts in the At a Glance widget. They should not be opted into a custom reaction type. The documentation says so rather than advertising them.

docs/adding-rules.md gains the registration step, the reserved asb- slug prefix and a note on the payload. docs/program-flow.md no longer leaves Handlers\Rules looking like the way in.

Testing

composer test:unit — 56 tests pass, 20 of them new. phpstan and phpcs clean.

Verified end to end against a local install with form-block ported to the new API, submitting real forms over HTTP:

Check	Result
BBCode submission	stored as spam, reason asb-bbcode
host derived from url	spam.example.com
Reaction type with stored options	only the ticked rule active; a new default does not re-enable a disabled rule
Same reaction type with its stored options removed	all four opted-in rules active from defaults, nothing written to the database
Submission only RegexpSpam can catch, on defaults alone	stored as spam, reason asb-regexp
spam_count throughout	unchanged at 0 — no post-processor ran, the comment counter is untouched

Notes for review

• SpamCheck::check() fails open, matching current behaviour for an empty rule set: it catches the ReflectionException that Rules::get()/apply() declare, logs, and returns a not-evaluated result rather than surfacing a Reflection error to integrators.
• API_VERSION is there so integrations can adapt to a breaking change; everything outside AntispamBee\Api and the documented hooks is stated to be internal.
• The counter stays comment-scoped. A per-reaction-type counter would need new user-facing strings, i18n and a migration for the flat spam_count, and nothing requires it yet.

[Zodiac1978]

Related #768

[MatzeKitt]

Successfully tested with epiphyt/form-block#83 🎉

[github-actions]

🔍 WordPress Plugin Check Report

❌ Status: Failed

📊 Report

🎯 Total Issues	❌ Errors	⚠️ Warnings
1	1	0

---

❌ Errors (1)

📁 readme.txt (1 error)

📍 Line	🔖 Check	💬 Message
0	outdated_tested_upto_header	Tested up to: 7.0 < 7.1. The "Tested up to" value in your plugin is not set to the current version of WordPress. This means your plugin will not show up in searches, as we require plugins to be compatible and documented as tested up to the most recent version of WordPress.

---

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check