pixelopen/cloudflare-turnstile-bundle

A simple package to help integrate Cloudflare Turnstile on Symfony.

0.5.0 2026-03-08 19:47 UTC

Requires

• php: >=8.2
• symfony/form: ^5.0|^6.0|^7.0|^8.0
• symfony/framework-bundle: ^5.0|^6.0|^7.0|^8.0
• symfony/http-client: ^5.0|^6.0|^7.0|^8.0
• symfony/twig-bundle: ^5.0|^6.0|^7.0|^8.0
• symfony/validator: ^5.0|^6.0|^7.0|^8.0
• symfony/yaml: ^5.0|^6.0|^7.0|^8.0

Requires (Dev)

• phpstan/phpstan: ^2.0
• phpstan/phpstan-symfony: ^2.0
• phpunit/phpunit: ^10.0|^11.0
• rector/rector: ^2.0
• symplify/easy-coding-standard: ^12.0

MIT

• Pixel Open Team

• captcha
• Symfony Bundle
• form security
• cloudflare-turnstile

README

This packages provides helper for setting up and validating Cloudflare Turnstile CAPTCHA responses.

Installation

You can install the package via Composer:

composer require pixelopen/cloudflare-turnstile-bundle

Add bundle into config/bundles.php file :

PixelOpen\CloudflareTurnstileBundle\PixelOpenCloudflareTurnstileBundle::class => ['all' => true]

Add a config file into config/packages/pixel_open_cloudflare_turnstile.yaml :

pixel_open_cloudflare_turnstile:
  key: '%env(TURNSTILE_KEY)%'
  secret: '%env(TURNSTILE_SECRET)%'
  enable : true

Visit Cloudflare to create your site key and secret key and add them to your .env file.

TURNSTILE_KEY="1x00000000000000000000AA"
TURNSTILE_SECRET="2x0000000000000000000000000000000AA"

Use with your Symfony Form

Create a form type and insert an Turnstile Type to add a Cloudflare Turnstile :

<?php

namespace App\Form;

use App\Entity\Contact;
use PixelOpen\CloudflareTurnstileBundle\Type\TurnstileType;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class ContactType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('name', TextType::class, ['label' => false, 'attr' => ['placeholder' => 'name']])
            ->add('message', TextareaType::class, ['label' => false, 'attr' => ['placeholder' => 'message']])
            ->add('security', TurnstileType::class, ['attr' => ['data-action' => 'contact', 'data-theme' => 'dark'], 'label' => false])
            ->add('submit', SubmitType::class)
        ;
    }

    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'data_class' => Contact::class,
        ]);
    }
}

Use with PHP Attributes

Since Symfony 5.2, you can use the CloudflareTurnstile constraint as a PHP attribute directly on your DTO or entity properties:

<?php

namespace App\Model;

use PixelOpen\CloudflareTurnstileBundle\Validator\CloudflareTurnstile;

class ContactData
{
    public string $name = '';

    public string $message = '';

    #[CloudflareTurnstile]
    public string $turnstileToken = '';
}

You can also customize the violation message:

#[CloudflareTurnstile(message: 'captcha.invalid')]
public string $turnstileToken = '';

Testing

Use the following sitekeys and secret keys for testing purposes:

Sitekey

Sitekey	Description
1x00000000000000000000AA	Always passes
2x00000000000000000000AB	Always blocks
3x00000000000000000000FF	Forces an interactive challenge

Secret key

Secret key	Description
1x0000000000000000000000000000000AA	Always passes
2x0000000000000000000000000000000AA	Always fails
3x0000000000000000000000000000000AA	Yields a "token already spent" error

Todo

• Add phpunit to test field and validator

License

The MIT License (MIT). Please see License File for more information.