How to Integrate hCaptcha with phpBB

How do you integrate hCaptcha with phpBB?#

Install Alfredo Ramos's community hCaptcha extension for phpBB, enable it in the Administration Control Panel, and select hCaptcha under Spambot countermeasures. Add your sitekey and account secret, choose the widget theme and size, and test every board workflow that invokes the active CAPTCHA provider.

This guide covers Alfredo Ramos's hCaptcha extension for phpBB 3.3.

These instructions were last validated on September 16, 2026 with extension 1.1.0 on phpBB 3.3.15.

Reduce CAPTCHA interruptions on your phpBB board#

• Ask less of legitimate participants. With hCaptcha Pro's 99.9% Passive mode, fewer than 0.1% of legitimate users receive a challenge on registration, guest, and other board workflows invoking the hCaptcha provider.
• Increase verification when activity looks suspicious. Pro adjusts challenge difficulty as risk rises, helping you keep participation less disruptive while applying stronger checks to higher-risk attempts.

New Pro sitekeys use 99.9% Passive by default. For an existing sitekey upgraded to Pro, select that mode under Behavior in the hCaptcha dashboard.

Before you start#

You need:

• A phpBB installation and PHP runtime that satisfy the current extension requirements.
• File access to the phpBB installation and administrator access to the ACP.
• An hCaptcha account that can create a sitekey and securely manage its matching secret.
• Access to test the registration, login, guest, or extension-provided workflows that use phpBB's CAPTCHA provider.

Create your hCaptcha credentials#

1. Start with hCaptcha Pro for fewer challenges and adaptive protection on protected phpBB community workflows, or use existing compatible hCaptcha credentials.
2. Create a sitekey for the phpBB hostname.
3. Add the production hostname and any separate staging hostname assigned to that sitekey.
4. Use the matching secret saved during account setup. If it is unavailable, generate a replacement in dashboard Settings, save it securely, and update integrations using the old secret; generating a new secret rotates it.
5. Limit ACP access to administrators who need to configure the integration.

The sitekey renders hCaptcha in the browser. The secret authorizes verification and must remain in server-managed phpBB settings. We list phpBB in our integration catalog and integrations-list repository.

Download and install the phpBB extension#

Download version 1.1.0 or a later reviewed release from the official phpBB extension page. Its source repository provides the implementation and current package requirements.

1. Decompress the downloaded archive.
2. Copy its contents to {PHPBB_ROOT}/ext/alfredoramos/hcaptcha/.
3. Sign in to the phpBB ACP.
4. Open Customise > Manage extensions.
5. Find hCaptcha, select Enable, and confirm.
6. Confirm that version 1.1.0 or a later reviewed version is active.

Preserve the exact vendor and extension directory names. phpBB will not discover the extension from an arbitrary folder.

Configure hCaptcha in the ACP#

1. Open General > Board configuration > Spambot countermeasures.
2. In Available plugins, select hCaptcha from the installed CAPTCHA plugins.
3. Select Configure.
4. Paste the hCaptcha sitekey into Site key.
5. Paste the matching account secret into Secret key.
6. Choose the Light or Dark theme.
7. Choose the Normal or Compact widget size.
8. Review the option governing hCaptcha for registered-user login.
9. Submit the settings and confirm that the hCaptcha preview renders.

The extension becomes phpBB's CAPTCHA provider. phpBB core and compatible extensions decide where that provider appears, so confirm the board's active spambot settings and workflow-specific extension configuration.

Verify the phpBB integration#

Version 1.1.0 reads h-captcha-response and sends the response, sitekey, secret, and visitor IP to hCaptcha with a server-side POST. It marks the CAPTCHA solved only when hCaptcha reports success.

1. Open each protected workflow in a private browser window and confirm that hCaptcha renders.
2. Complete hCaptcha and submit valid data. Confirm that the intended registration, login, post, or contact action happens once.
3. Submit without a valid response and confirm that phpBB blocks the action.
4. Test anonymous visitors, registered users, and administrators when their workflows differ.
5. Retest custom styles, extensions that display phpBB CAPTCHA, caches, and Content Security Policy settings.

Do not assume a working registration challenge proves that login, guest posting, or a separate Contact Admin extension is protected. Exercise every workflow the board exposes.

Troubleshoot common phpBB problems#

hCaptcha does not appear in Manage extensions

Confirm that the files are located at ext/alfredoramos/hcaptcha/ and that the installed phpBB and PHP versions meet the current package requirements. Clear phpBB's cache after correcting the directory.

hCaptcha is unavailable under Spambot countermeasures

Confirm that the extension is enabled and that both the sitekey and secret are saved. Update the extension if it does not accept the current hCaptcha secret format.

The widget renders, but every request fails

Confirm that the sitekey and secret belong to the same hCaptcha account and cover the active hostname. Check outbound HTTPS access from the phpBB server and review logs without exposing the secret.

A specific form does not show hCaptcha

Check whether phpBB core or the extension that owns that form invokes the configured CAPTCHA provider. Compatibility with one workflow does not automatically add hCaptcha to every form.

Choose Pro or discuss an Enterprise deployment#

hCaptcha Pro is the self-service path for phpBB. It includes 99.9% Passive mode, custom themes, more detailed analytics, and multi-user account access.

Organizations operating several boards, higher-volume communities, risk-score workflows, custom threat models, centralized access requirements, or contractual service needs should plan the deployment with our team. Review extension compatibility, credential ownership, workflow coverage, and rollout monitoring before launch.

FAQ#

Which phpBB versions support this hCaptcha extension?

Confirm that the installed phpBB and PHP versions satisfy the current extension requirements.

Where should the extension files be installed?

Place them under {PHPBB_ROOT}/ext/alfredoramos/hcaptcha/, then enable hCaptcha through Customise > Manage extensions in the ACP.

Does the extension verify hCaptcha on the server?

Yes. It sends the submitted token and matching credentials to hCaptcha from phpBB and accepts the challenge only after a successful response.

Which phpBB forms does hCaptcha protect?

The extension supplies phpBB's CAPTCHA provider. The phpBB core or a compatible extension controls when that provider appears, so verify each registration, login, guest, or contact workflow used by the board.

Can administrators change the widget appearance?

Yes. Version 1.1.0 provides Light and Dark themes and Normal and Compact widget sizes in the ACP configuration.