Recaptcha Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require couss/recaptcha-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Couss\FrancisReCaptchaBundle\CoussFrancisReCaptchaBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console recaptcha:install
   

   Update config/packages/couss_francis_recaptcha.yaml with your Google reCAPTCHA v2/v3 site key and secret key.

3. First Use Case Add the field to a form type:

   use Couss\FrancisReCaptchaBundle\Form\Type\ReCaptchaType;
   
   $builder->add('recaptcha', ReCaptchaType::class, [
       'mapped' => false, // Always false (not stored in DB)
       'type' => 'v2',    // 'v2' or 'v3'
       'theme' => 'light', // Optional: 'light' or 'dark'
   ]);
   

Implementation Patterns

Common Workflows

1. Form Validation The bundle auto-validates reCAPTCHA responses. Add the constraint to your entity:

   use Couss\FrancisReCaptchaBundle\Validator\Constraints\ReCaptcha;
   
   /**
    * @Assert\Valid()
    * @ReCaptcha(type="v2")
    */
   private $recaptchaResponse;
   

2. Dynamic Field Rendering Use Twig to conditionally render reCAPTCHA:

   {% if showRecaptcha %}
       {{ form_widget(form.recaptcha) }}
   {% endif %}
   

3. API/Non-Form Use Manually verify tokens in controllers:

   use Couss\FrancisReCaptchaBundle\Service\ReCaptchaService;
   
   $service = $this->container->get(ReCaptchaService::class);
   $isValid = $service->verify($responseToken, 'v2');
   

Integration Tips

• Symfony UX Turbo/Stimulus: Re-render the field after AJAX submissions.
• Custom Error Messages: Override validation messages in config/validation.yaml:

  Couss\FrancisReCaptchaBundle\Validator\Constraints\ReCaptcha:
      message: "Invalid reCAPTCHA. Please try again."
  

• Environment-Specific Keys: Use %env(RECAPTCHA_SECRET)% in config for security.

Gotchas and Tips

Pitfalls

1. Secret Key Exposure

   • Never commit config/packages/couss_francis_recaptcha.yaml to version control.
   • Use environment variables or Symfony’s %env% syntax.

2. Version Mismatch

   • The bundle supports reCAPTCHA v2 (checkbox/invisible) and v3 (score-based). Ensure your Google keys match the version.
   • v3 requires a minimum score (default: 0.5). Adjust in config:

     recaptcha:
         v3:
             min_score: 0.7
     

3. Caching Issues

   • reCAPTCHA responses are not cached by default. For high-traffic sites, implement a short-lived cache (e.g., Redis) for verification tokens.

4. Form Submission Quirks

   • If using v3, the recaptcha field is hidden. Ensure your frontend sends the token via JavaScript:

     grecaptcha.ready(() => {
         grecaptcha.execute('SITE_KEY', { action: 'submit' }).then(token => {
             document.getElementById('recaptcha_token').value = token;
         });
     });
     

Debugging

• Enable Debug Mode: Add to config:

  recaptcha:
      debug: true
  

  Logs verification attempts to var/log/dev.log.

• Test Locally: Use Google’s test keys:

  • Site Key: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI
  • Secret Key: 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

Extension Points

1. Custom Verifier Implement Couss\FrancisReCaptchaBundle\Service\ReCaptchaVerifierInterface for enterprise APIs (e.g., proxy verification).

2. Twig Extensions Add custom filters to modify reCAPTCHA HTML:

   {{ form_widget(form.recaptcha) | recaptcha_attr({'class': 'my-class'}) }}
   

   Extend the bundle’s ReCaptchaType to add this filter.

3. Event Listeners Subscribe to recaptcha.verify events to log failed attempts:

   // src/EventListener/ReCaptchaListener.php
   public function onVerify(ReCaptchaEvent $event) {
       if (!$event->isValid()) {
           // Log IP, user agent, etc.
       }
   }