Shield silentCAPTCHA Integration Guide

This guide is framework-agnostic. It defines the integration contract for consuming Shield silentCAPTCHA in any form or request-processing system.

1) Shield functions to integrate

Use these two Shield functions. Try namespaced first, then global fallback.

A) Bot verdict function (used to decide block/allow)

• Primary: \FernleafSystems\Wordpress\Plugin\Shield\Functions\test_ip_is_bot
• Fallback: \shield_test_ip_is_bot
• Signature: test_ip_is_bot( $IP = null ): bool
• Meaning:
  • true => Shield says this IP is a bot
  • false => Shield says this IP is not a bot
• Notes:
  • Do not pass an explicit IP address. Call without arguments and let Shield determine the visitor IP itself.
  • In rare cases (e.g. plugin misconfiguration), the function may throw an error or exception. Wrap calls in try/catch (\Throwable $e) to ensure this never propagates into your application.

Use this function during submission validation. This is the function that drives enforcement.

B) Threshold function (used to detect if silentCAPTCHA is disabled)

• Primary: \FernleafSystems\Wordpress\Plugin\Shield\Functions\get_silentcaptcha_bot_threshold
• Fallback: \shield_get_silentcaptcha_bot_threshold
• Signature: get_silentcaptcha_bot_threshold(): int
• Meaning:
  • numeric 0 => silentCAPTCHA is disabled in Shield's configuration
  • non-zero => silentCAPTCHA is active with a configured threshold
• Notes:
  • In rare cases (e.g. plugin misconfiguration), the function may throw an error or exception. Wrap calls in try/catch (\Throwable $e) to ensure this never propagates into your application.

Use this function to detect whether silentCAPTCHA is disabled. When the threshold is 0, Shield is installed but silentCAPTCHA is not active — display a notice in the UI to alert the user.

2) Resolution and call method

For each function type (bot verdict and threshold), resolve in this order:

1. namespaced callable
2. global fallback callable

Call pattern:

1. is_callable($fn) before calling
2. call_user_func($fn) wrapped in try/catch (\Throwable $e) — in rare cases (e.g. plugin misconfiguration), Shield functions may throw. Catching \Throwable ensures no error or exception propagates into your application.
3. if callable missing or throws: continue to the next fallback, or fail-open

3) Enforcement flow

Run this in your earliest centralized validation stage:

1. exit if request should not be validated (invalid context, pre-check, etc.)
2. exit if previous validators already produced blocking errors
3. exit if your integration is disabled
4. resolve/call bot verdict function (without passing an IP — let Shield determine it)
5. block only when result is strict true
6. allow when result is strict false

4) Suggested toggle model

• Global toggle: enable/disable Shield integration system-wide
• Local toggle: optional per-form/per-endpoint enable flag
• Evaluate Shield only when all required toggles are enabled

5) Threshold check pattern

1. check Shield availability via bot verdict function availability
2. if available, check whether silentCAPTCHA is enabled (threshold > 0)
3. if silentCAPTCHA is disabled, display a UI notice alerting the user
4. ignore missing callable or throwable results (fail-open)

6) Pseudocode

The following examples demonstrate how to implement the resolution and enforcement patterns described above. Adapt these to fit your framework and coding conventions.

/**
 * Returns true if the visitor is a bot, false if not, or null if Shield is unavailable.
 */
function resolve_shield_bot_verdict() {
    $callables = [
        '\FernleafSystems\Wordpress\Plugin\Shield\Functions\test_ip_is_bot',
        '\shield_test_ip_is_bot',
    ];

    foreach ( $callables as $fn ) {
        if ( is_callable( $fn ) ) {
            try {
                return call_user_func( $fn ); // bool — Shield determines the visitor IP
            }
            catch ( \Throwable $e ) {
            }
        }
    }

    // Shield is not available (not installed, or callable threw an exception).
    // Return null so the caller can fail-open and allow the request.
    return null;
}

/**
 * Returns true if silentCAPTCHA is enabled, false if disabled, or null if Shield is unavailable.
 */
function is_shield_silentcaptcha_enabled() {
    $callables = [
        '\FernleafSystems\Wordpress\Plugin\Shield\Functions\get_silentcaptcha_bot_threshold',
        '\shield_get_silentcaptcha_bot_threshold',
    ];

    foreach ( $callables as $fn ) {
        if ( is_callable( $fn ) ) {
            try {
                return call_user_func( $fn ) > 0;
            }
            catch ( \Throwable $e ) {
            }
        }
    }

    // Threshold function is not available — silentCAPTCHA status is unknown.
    return null;
}

// --- Bot verdict: block or allow the request ---

$verdict = resolve_shield_bot_verdict();
if ( $verdict === true ) {
    // block submission — Shield identified this visitor as a bot
}
elseif ( $verdict === false ) {
    // allow submission — Shield confirmed this visitor is not a bot
}
else {
    // $verdict is null — Shield is unavailable. Fail-open and allow the request.
}

// --- silentCAPTCHA status: alert the user if disabled ---

$enabled = is_shield_silentcaptcha_enabled();
if ( $enabled === false ) {
    // Shield is installed but silentCAPTCHA is disabled — display UI notice
}