Cloudflare Turnstile
(for phpBB)
A phpBB 3.3.x extension that integrates Cloudflare Turnstile as a CAPTCHA provider for registration, login, and guest posting, for modern bot protection.
Current Version:
1.2.5
( File Size: 57 KB )
Features
Registration, login, and guest posting protection with Cloudflare Turnstile.
- Registration Protection: Turnstile as a selectable CAPTCHA in ACP → Spambot countermeasures
- Login Protection: When Turnstile is the board CAPTCHA, choose when to require verification:
- After failed attempts
- Always
- Off
- Guest Posting Protection: Turnstile for Guest posts via ACP → Spambot countermeasures
- Widget Types: Visible or Invisible mode
- Widget Theme: Light, Dark, or Auto
- Widget Size: Scalable widget (100%, 80%, 60%) for registration and login forms
- ACP Live Preview: Real-time widget preview in extension settings
- Fail-Safe Options: Configurable behaviour when Cloudflare API is unreachable or errors:
- Fail-closed: Block submission (secure, may deny legitimate users)
- Fail-open: Allow submission (may allow bots through)
- Logging: API errors logged to phpBB admin log
- Update Notifications: Automatic update checks with ACP notices and optional email alerts (since this is a security-focused extension, staying current matters)
- Multi-language Support: English, German, French, Spanish, and Italian
Requirements
- phpBB 3.3.0 or newer (up to 4.0.0)
- PHP 7.4.0 or newer
- Cloudflare account with Turnstile site key and secret key
Installing
- Extract the ZIP contents into your phpBB
ext/directory - Your folder structure should be:
ext/icecorp/turnstile/ - Go to ACP → Customise → Manage extensions
- Find Cloudflare Turnstile and click Enable
Configuring
Get Cloudflare Turnstile Keys
- Log into your Cloudflare Dashboard
- Go to Cloudflare Dashboard → Protect & Connect → Turnstile
- Add a new Turnstile widget
- Widget Mode: Set to Managed (recommended) or Non-Interactive. Do not select “Invisible” — this overrides the extension’s visibility settings and hides the widget regardless of your extension configuration.
- Copy your Site Key and Secret Key
Configure the Extension
Via ACP → Customise → Extensions → Cloudflare Turnstile:
- Site Key: Your Cloudflare Turnstile site key
- Secret Key: Your Cloudflare Turnstile secret key (keep confidential)
- Widget Type: Visible (users see widget) or Invisible (runs in background)
- Widget Theme: Auto (system preference), Light, or Dark
- Widget Size: Scale the widget — 100% (default), 80%, or 60%. Applies to registration and login pages; quick login uses a fixed smaller size.
- API Failure Behaviour: Fail closed (secure) or Fail open (available)
- Enable Update Checking: Turn automatic version checks on/off (checks every 24 hours)
- Email Notifications: Send email to board admin when updates are available
A live preview of the widget appears in the settings page when a valid site key is configured, showing the current theme and size settings.
Note: Automatic checks run approximately every 24 hours via phpBB’s cron system, which triggers on page visits by default. If Run periodic tasks from system cron is “enabled” in ACP → Server settings, ensure your system cron runs bin/phpbbcli.php cron:run regularly.
Registration Protection
- Go to ACP → General → Board configuration → Spambot countermeasures
- Select Cloudflare Turnstile as the spambot countermeasures plugin
- Click Submit
Login Protection
- After failed attempts: Turnstile appears after threshold set in ACP → Server configuration → Security settings
- Always: Turnstile on every login attempt
- Off: Requires “Maximum login attempts” to be 0 in the same Security settings
Note: After failed attempts and Always both require Cloudflare Turnstile as board CAPTCHA.
Guest Posting Protection
- Go to ACP → General → Board configuration → Spambot countermeasures
- Set Enable spambot countermeasures for guest postings to Enabled
- Ensure Cloudflare Turnstile is selected as the plugin
Updating
- Go to ACP → Customise → Manage extensions
- Disable Cloudflare Turnstile
- Delete the
ext/icecorp/turnstile/folder via FTP/File Manager - Extract the new ZIP contents into your phpBB
ext/directory - Your folder structure should be:
ext/icecorp/turnstile/ - Enable the extension
- Purge the cache
Uninstalling
Important: You must change the CAPTCHA setting before disabling the extension.
- Go to ACP → General → Board configuration → Spambot countermeasures
- Change the plugin to a different option (e.g., “No CAPTCHA” or “Q&A”)
- Click Submit
- Go to ACP → Customise → Manage extensions
- Click Disable for Cloudflare Turnstile
- Click Delete data to remove all extension data
- Delete the
ext/icecorp/turnstile/folder via FTP/File Manager
Troubleshooting
Locked out of login?
If you have Login Protection set to “Always” and API Failure Behaviour set to “Fail closed” (the default), you can get locked out if your Turnstile keys become invalid or Cloudflare’s API is unreachable.
To recover, run one of these SQL queries via phpMyAdmin or command line:
Disable login protection:
UPDATE phpbb_config SET config_value = '0' WHERE config_name = 'icecorp_turnstile_login_mode';
Or switch to fail-open mode:
UPDATE phpbb_config SET config_value = '1' WHERE config_name = 'icecorp_turnstile_fail_mode';
(Adjust phpbb_ prefix if your database uses a different table prefix.)
Widget not showing?
If you’ve set Widget Type to “Visible” in the extension but the widget doesn’t appear, check your Cloudflare Turnstile widget settings.
In the Cloudflare dashboard, Widget Mode must be set to Managed or Non-Interactive. If it’s set to “Invisible”, the widget will be hidden regardless of your extension settings — Cloudflare’s Invisible mode overrides the extension’s visibility configuration.
To fix: Go to Cloudflare Dashboard → Protect & Connect → Turnstile → Edit your widget → Change Widget Mode to Managed (recommended) → Save.
Support
phpBB.com Extensions in Development: [3.3][BETA] Cloudflare Turnstile
Changelog available in above phpBB.com link.
Feel free to reach out with feedback and questions using the form below.