README

A modern, zero-config Symfony bundle for hCaptcha: server-side verification, Twig widget, Form Type and Validation Constraint — ready in under a minute.

Languages / Langues / Idiomas: English · Français · Español

Features

Zero-config install via Symfony Flex
Strict-typed HcaptchaVerifier returning a rich HcaptchaResponse value object (success, errorCodes, hostname, score for Enterprise, …)
Symfony Form Type (HcaptchaType) with auto-attached validator
Symfony Validation Constraint (#[Hcaptcha]) for any DTO/property
Twig functions: hcaptcha_script(), hcaptcha_widget(), hcaptcha_invisible_widget()
HTTPS-only verify URL, attribute name allow-list, JS callback identifier check
Test-mode toggle (enabled: false) — no HTTP call, always succeeds
PSR-3 logging on transport failures
100% PHP 8.1+ / Symfony 6.4 LTS · 7.x compatible

Requirements

PHP 8.1 or higher
Symfony 6.4 LTS or 7.x

Quick install

composer require ethsam/easy-hcaptcha

Then in .env:

HCAPTCHA_SITE_KEY=your_public_site_key
HCAPTCHA_SECRET_KEY=your_secret_key

And in config/packages/easy_hcaptcha.yaml:

easy_hcaptcha:
    site_key:   '%env(HCAPTCHA_SITE_KEY)%'
    secret_key: '%env(HCAPTCHA_SECRET_KEY)%'

30-second usage

{# templates/contact.html.twig #}
<head>{{ hcaptcha_script() }}</head>
<form method="post">
    {{ hcaptcha_widget() }}
    <button>Send</button>
</form>

// In your controller — pick your favourite style:

// 1) Form Type (recommended — auto-validated)
$form = $this->createFormBuilder()
    ->add('email', EmailType::class)
    ->add('captcha', HcaptchaType::class)
    ->getForm();

// 2) Validation Constraint on a DTO
class ContactDto {
    #[\Ethsam\EasyHcaptcha\Validator\Constraint\Hcaptcha]
    public ?string $captchaToken = null;
}

// 3) Manual call (full control)
public function submit(Request $r, HcaptchaVerifierInterface $verifier): Response
{
    $result = $verifier->verify($r->request->get('h-captcha-response'), $r->getClientIp());
    if (!$result->isSuccess()) {
        return $this->redirectToRoute('contact');
    }
    // ...
}

Documentation

Full documentation in three languages:

English	Français	Español
📖 Index	📖 Index	📖 Índice
Installation	Installation	Instalación
Configuration	Configuration	Configuración
Twig usage	Utilisation Twig	Uso con Twig
Form Type	Form Type	Form Type
Validator	Validateur	Validador
Controller	Contrôleur	Controlador
Upgrade from 1.x	Migration depuis 1.x	Migración desde 1.x

Testing your app without hitting the API

In config/packages/test/easy_hcaptcha.yaml:

easy_hcaptcha:
    enabled: false   # verifier returns success without any network call

Contributing

Pull requests welcome. Run the test suite locally:

composer install
vendor/bin/phpunit

Changelog

See CHANGELOG.md for a detailed history of releases.

License

Released under the MIT License — see the file for details.

Originally authored by Samuel ETHEVE.

ethsam / easy-hcaptcha

Maintainers

Package info

Statistics

Security