> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/captcha/adapters.md).

# Adapters

Quantum exposes the same `captcha()` API for both built-in providers. Choose the adapter based on the provider you want to embed in your forms.

## Choosing an adapter

* Use `recaptcha` when your project is configured for Google reCAPTCHA.
* Use `hcaptcha` when your project is configured for hCaptcha.

```php
$captcha = captcha('recaptcha');
```

If you omit the adapter name, Quantum resolves `captcha.default`.

## Shared config contract

Each adapter expects a config block under `config/captcha.php`:

```php
return [
    'default' => 'recaptcha',

    'recaptcha' => [
        'type' => 'visible',
        'secret_key' => '...',
        'site_key' => '...',
    ],

    'hcaptcha' => [
        'type' => 'visible',
        'secret_key' => '...',
        'site_key' => '...',
    ],
];
```

Required keys per adapter:

* `secret_key`
* `site_key`

Optional key:

* `type` - `visible` or `invisible`

## reCAPTCHA adapter

Use `recaptcha` for Google's widget and verification endpoint.

### Runtime behavior

* renders markup with the `g-recaptcha` class
* loads `https://www.google.com/recaptcha/api.js`
* verifies responses through Google's `siteverify` endpoint
* expects the request field name `g-recaptcha-response`

## hCaptcha adapter

Use `hcaptcha` for hCaptcha's widget and verification endpoint.

### Runtime behavior

* renders markup with the `h-captcha` class
* loads `https://hcaptcha.com/1/api.js?onload=onLoadCallback&recaptchacompat=off`
* verifies responses through hCaptcha's `siteverify` endpoint
* expects the request field name `h-captcha-response`

## Shared adapter behavior

Both adapters share these rules:

* they support `visible` and `invisible` modes only
* `addToForm()` returns HTML or inline script, it does not write directly to the response
* `verify()` performs a GET request with `secret`, `response`, and `remoteip`
* `getErrorMessage()` returns the first stored error code, or `null` when no error has been recorded

## Caveats

* adapter construction assumes the configured keys exist; missing config values surface as runtime failures from PHP or later verification failures
* invisible mode wires the provider class onto `button[type=submit]` inside the target form, so custom JavaScript-only submit flows need to account for that
* the package does not normalize provider-specific error codes into friendlier messages


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/captcha/adapters.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.