### Install Bundle via Composer

Source: https://github.com/pixel-open/cloudflare-turnstile-bundle/blob/develop/README.md

Run this command in your terminal to add the bundle to your project dependencies.

```bash
composer require pixelopen/cloudflare-turnstile-bundle
```

--------------------------------

### Set Environment Variables

Source: https://github.com/pixel-open/cloudflare-turnstile-bundle/blob/develop/README.md

Add your Cloudflare site and secret keys to your .env file.

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

--------------------------------

### Register Bundle in Symfony

Source: https://github.com/pixel-open/cloudflare-turnstile-bundle/blob/develop/README.md

Add the bundle class to your config/bundles.php file to enable it.

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

--------------------------------

### Configure Testing Keys

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

Define test keys in your configuration to simulate different Turnstile verification outcomes during development.

```yaml
# config/packages/dev/pixel_open_cloudflare_turnstile.yaml
pixel_open_cloudflare_turnstile:
  # Always passes - use for development
  key: '1x00000000000000000000AA'
  secret: '1x0000000000000000000000000000000AA'
  enable: true

# Alternative test configurations:
# Always blocks:
#   key: '2x00000000000000000000AB'
#   secret: '2x0000000000000000000000000000000AA'
#
# Forces interactive challenge:
#   key: '3x00000000000000000000FF'
#   secret: '1x0000000000000000000000000000000AA'
#
# Token already spent error:
```

--------------------------------

### Configure Turnstile Settings

Source: https://github.com/pixel-open/cloudflare-turnstile-bundle/blob/develop/README.md

Define the bundle configuration in a YAML file within your Symfony packages directory.

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

--------------------------------

### Configure Cloudflare Turnstile Bundle

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

Configure the bundle in `config/packages/pixel_open_cloudflare_turnstile.yaml` using your Cloudflare Turnstile site key and secret key. The `enable` option can disable validation globally.

```yaml
# config/packages/pixel_open_cloudflare_turnstile.yaml
pixel_open_cloudflare_turnstile:
  key: '%env(TURNSTILE_KEY)%'
  secret: '%env(TURNSTILE_SECRET)%'
  enable: true
```

--------------------------------

### Set Cloudflare Turnstile API Keys in .env

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

Define the `TURNSTILE_KEY` and `TURNSTILE_SECRET` environment variables in your `.env` file.

```bash
# .env
TURNSTILE_KEY="1x00000000000000000000AA"
TURNSTILE_SECRET="2x0000000000000000000000000000000AA"
```

--------------------------------

### Manual Verification with CloudflareTurnstileHttpClient

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

Use the CloudflareTurnstileHttpClient service for manual token verification outside of the standard Symfony validator flow.

```php
<?php

namespace App\Service;

use PixelOpen\CloudflareTurnstileBundle\Http\CloudflareTurnstileHttpClient;
use Psr\Log\LoggerInterface;

class CustomVerificationService
{
    public function __construct(
        private readonly CloudflareTurnstileHttpClient $turnstileClient,
        private readonly LoggerInterface $logger,
    ) {
    }

    public function verifyAndProcess(string $turnstileResponse, array $formData): array
    {
        // Manually verify the Turnstile response
        $isValid = $this->turnstileClient->verifyResponse($turnstileResponse);

        if (!$isValid) {
            $this->logger->warning('Turnstile verification failed', [
                'ip' => $formData['ip'] ?? 'unknown',
            ]);

            return [
                'success' => false,
                'error' => 'CAPTCHA verification failed. Please try again.',
            ];
        }

        $this->logger->info('Turnstile verification successful');

        // Continue with business logic
        return [
            'success' => true,
            'message' => 'Verification passed, processing request.',
        ];
    }
}
```

--------------------------------

### Register Cloudflare Turnstile Bundle in Symfony

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

Register the bundle in your Symfony application's `config/bundles.php` file to enable its services.

```php
// config/bundles.php
return [
    // ... other bundles
    PixelOpen\CloudflareTurnstileBundle\PixelOpenCloudflareTurnstileBundle::class => ['all' => true],
];
```

--------------------------------

### Test Contact Form Submission with Turnstile

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

This test demonstrates submitting a contact form with Cloudflare Turnstile enabled. With test keys configured, the Turnstile widget automatically passes validation.

```php
<?php

namespace App\Tests\Controller;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class ContactControllerTest extends WebTestCase
{
    public function testContactFormSubmission(): void
    {
        $client = static::createClient();
        $crawler = $client->request('GET', '/contact');

        // With test keys configured, the Turnstile widget will auto-pass
        $form = $crawler->selectButton('Send Message')->form([
            'contact[name]' => 'John Doe',
            'contact[email]' => 'john@example.com',
            'contact[message]' => 'This is a test message.',
        ]);

        $client->submit($form);

        $this->assertResponseRedirects('/contact/success');
    }

    public function testDisabledTurnstileInTestEnvironment(): void
    {
        // When enable: false is set, validation is skipped entirely
        $client = static::createClient(['environment' => 'test']);
        $crawler = $client->request('GET', '/contact');

        $form = $crawler->selectButton('Send Message')->form([
            'contact[name]' => 'Jane Doe',
            'contact[email]' => 'jane@example.com',
            'contact[message]' => 'Testing with Turnstile disabled.',
        ]);

        $client->submit($form);

        $this->assertResponseIsSuccessful();
    }
}

```

--------------------------------

### Apply Turnstile Validation via Attributes

Source: https://github.com/pixel-open/cloudflare-turnstile-bundle/blob/develop/README.md

Use the CloudflareTurnstile attribute on DTO or entity properties to enforce validation.

```php
<?php

namespace App\Model;

use PixelOpen\CloudflareTurnstileBundle\Validator\CloudflareTurnstile;

class ContactData
{
    public string $name = '';

    public string $message = '';

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

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

--------------------------------

### Apply CloudflareTurnstile Constraint to DTO

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

Use the CloudflareTurnstile attribute on DTO properties to enable validation outside of standard forms.

```php
<?php

namespace App\Model;

use PixelOpen\CloudflareTurnstileBundle\Validator\CloudflareTurnstile;
use Symfony\Component\Validator\Constraints as Assert;

class ContactRequest
{
    #[Assert\NotBlank(message: 'Please enter your name')]
    #[Assert\Length(max: 100)]
    public string $name = '';

    #[Assert\NotBlank(message: 'Please enter your email')]
    #[Assert\Email]
    public string $email = '';

    #[Assert\NotBlank(message: 'Please enter a message')]
    #[Assert\Length(min: 10, max: 1000)]
    public string $message = '';

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

--------------------------------

### Twig Template for Contact Form with Turnstile

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

This Twig template renders a contact form, including the Turnstile widget. The Turnstile widget renders automatically when included as a form row. Errors from Turnstile validation are displayed below the widget.

```twig
{# templates/contact/index.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
<div class="contact-form">
    <h1>Contact Us</h1>

    {% for message in app.flashes('success') %}
        <div class="alert alert-success">{{ message }}</div>
    {% endfor %}

    {{ form_start(form) }}
        {{ form_row(form.name) }}
        {{ form_row(form.email) }}
        {{ form_row(form.message) }}

        {# Turnstile widget renders automatically #}
        {{ form_row(form.security) }}

        {# Display Turnstile errors if validation fails #}
        {{ form_errors(form.security) }}

        {{ form_row(form.submit) }}
    {{ form_end(form) }}
</div>
{% endblock %}

```

--------------------------------

### Implement TurnstileType in a Symfony Form

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

Add the `TurnstileType` to your Symfony form to render the Cloudflare Turnstile widget. It includes validation and is unmapped by default. Custom attributes like `data-action`, `data-theme`, and `data-size` can be configured.

```php
<?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\EmailType;
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' => 'Your Name',
                'attr' => ['placeholder' => 'Enter your name']
            ])
            ->add('email', EmailType::class, [
                'label' => 'Email Address',
                'attr' => ['placeholder' => 'your@email.com']
            ])
            ->add('message', TextareaType::class, [
                'label' => 'Message',
                'attr' => ['placeholder' => 'Your message here...', 'rows' => 5]
            ])
            ->add('security', TurnstileType::class, [
                'label' => false,
                'attr' => [
                    'data-action' => 'contact',      // Custom action identifier
                    'data-theme' => 'dark',          // Widget theme: light, dark, or auto
                    'data-size' => 'normal',         // Widget size: normal or compact
                ]
            ])
            ->add('submit', SubmitType::class, [
                'label' => 'Send Message'
            ]);
    }

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

--------------------------------

### Validate Turnstile Token in Controller

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

Inject ValidatorInterface to validate the DTO containing the Turnstile token within a controller action.

```php
<?php

namespace App\Controller;

use App\Model\ContactRequest;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Validator\Validator\ValidatorInterface;

class ApiContactController extends AbstractController
{
    #[Route('/api/contact', name: 'api_contact', methods: ['POST'])]
    public function submit(Request $request, ValidatorInterface $validator): JsonResponse
    {
        $data = json_decode($request->getContent(), true);

        $contactRequest = new ContactRequest();
        $contactRequest->name = $data['name'] ?? '';
        $contactRequest->email = $data['email'] ?? '';
        $contactRequest->message = $data['message'] ?? '';
        $contactRequest->turnstileToken = $data['cf-turnstile-response'] ?? '';

        $errors = $validator->validate($contactRequest);

        if (count($errors) > 0) {
            $errorMessages = [];
            foreach ($errors as $error) {
                $errorMessages[$error->getPropertyPath()] = $error->getMessage();
            }
            return new JsonResponse(['errors' => $errorMessages], 400);
        }

        // Process the valid contact request
        return new JsonResponse(['success' => true, 'message' => 'Contact submitted successfully']);
    }
}
```

--------------------------------

### Integrate Turnstile in Symfony Form

Source: https://github.com/pixel-open/cloudflare-turnstile-bundle/blob/develop/README.md

Use the TurnstileType within a FormBuilder to add the CAPTCHA field to your form.

```php
<?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,
        ]);
    }
}
```

--------------------------------

### Symfony Controller Handling Turnstile Validation

Source: https://context7.com/pixel-open/cloudflare-turnstile-bundle/llms.txt

This controller action handles a contact form submission, including Turnstile validation. Turnstile validation passes automatically if the constraint is correctly configured. Errors, including Turnstile failures, are available if validation fails.

```php
<?php

namespace App\Controller;

use App\Entity\Contact;
use App\Form\ContactType;
use App\Repository\ContactRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class ContactController extends AbstractController
{
    #[Route('/contact', name: 'contact')]
    public function index(Request $request, ContactRepository $repository): Response
    {
        $contact = new Contact();
        $form = $this->createForm(ContactType::class, $contact);

        $form->handleRequest($request);

        if ($form->isSubmitted() && $form->isValid()) {
            // Turnstile validation passed automatically via the constraint
            $repository->save($contact, true);

            $this->addFlash('success', 'Your message has been sent successfully!');

            return $this->redirectToRoute('contact_success');
        }

        // If validation fails, errors including Turnstile failures are available
        return $this->render('contact/index.html.twig', [
            'form' => $form,
        ]);
    }

    #[Route('/contact/success', name: 'contact_success')]
    public function success(): Response
    {
        return $this->render('contact/success.html.twig');
    }
}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.