Shortcodes and helper functions

Updated September 13, 2026

Four shortcodes and a handful of PHP functions make up the plugin’s public surface. The shortcodes cover the common cases; the functions are what you reach for when writing an integration.

Shortcodes

[simple-turnstile] — a generic widget with a randomly generated unique id. Use it anywhere you want a widget in page content.
[cf7_simple_turnstile] — the Contact Form 7 form-tag. Must be placed in the CF7 form template so CF7 substitutes it during its own render. The older [cf7-simple-turnstile] still works.
[gravity-simple-turnstile id="3"] — for Gravity Forms. The id attribute is required and is the Gravity form id.
[mc4wp-simple-turnstile] — for Mailchimp for WordPress, placed in the MC4WP form editor.

All of them render nothing when the visitor is whitelisted, leaving the surrounding form markup untouched.

cfturnstile_field_show()

Prints widget markup. Returns nothing.

cfturnstile_field_show(
    string $button_id = '',   // CSS selector of the submit button
    string $callback  = '',   // JS callback invoked on a successful challenge
    string $form_name = '',   // becomes data-action, and the analytics label
    string $unique_id = '',   // suffix for the widget DOM id
    string $class     = ''    // extra CSS classes on the container
): void

It handles whitelisting, the disable filter, failsafe rendering and script enqueuing internally, so calling it is normally all an integration needs to do for the render half.

Pass a genuinely unique $unique_id — the bundled integrations use wp_rand() or the form id. Duplicate DOM ids mean Cloudflare renders into the first match only, and the rest stay empty.

cfturnstile_check()

Verifies a submitted token.

cfturnstile_check(
    string $postdata    = '',  // token; falls back to $_POST['cf-turnstile-response']
    string $form_action = ''   // form identifier, passed to cfturnstile_after_check
): array

Returns an array with success, plus error_code when it fails. It returns success early, without calling Cloudflare, when the visitor is whitelisted or the disable filter returns true, and it handles failsafe internally including the reCAPTCHA fallback.

Tokens are single-use. Calling this twice for the same submission fails the second time — which is exactly why the login and register skip filters exist.

Other functions

cfturnstile_whitelisted() — whether Turnstile should be skipped for this visitor.
cfturnstile_get_ip() — the visitor IP, preferring CF-Connecting-IP and rejecting private and reserved ranges.
cfturnstile_failed_message() — the configured error message, or the translated default.
cfturnstile_error_message( $code ) — human-readable text for a Cloudflare error code.
cfturnstile_is_cloudflare_down() — whether failsafe mode should engage.

How can we help?