Recaptcha Laravel Package

Getting Started

Minimal Steps

1. Install the Package Run:

   composer require 2latlantik/recaptcha
   

2. Register the Bundle Add to config/bundles.php:

   Delatlantik\RecaptchaBundle\RecaptchaBundle::class => ['all' => true],
   

3. Configure Keys Add your Google reCAPTCHA keys to config/packages/recaptcha.yaml:

   recaptcha:
       key: "your_public_key_here"
       secret: "your_private_key_here"
   

4. First Use Case Integrate into a Symfony form:

   use Delatlantik\RecaptchaBundle\Form\Type\RecaptchaSubmitType;
   
   $builder->add('recaptcha', RecaptchaSubmitType::class);
   

Implementation Patterns

Workflows

1. Form Integration

   • Use RecaptchaSubmitType in Symfony forms for seamless validation.
   • Example:

     $form = $this->createFormBuilder()
         ->add('name', TextType::class)
         ->add('recaptcha', RecaptchaSubmitType::class, [
             'label' => 'Verify you are not a robot',
         ])
         ->getForm();
     

2. Invisible reCAPTCHA

   • The bundle supports invisible reCAPTCHA by default. Ensure your Google keys are configured for the correct version.

3. Custom Validation

   • Extend validation logic by overriding the RecaptchaSubmitType or using Symfony’s validation constraints:

     use Delatlantik\RecaptchaBundle\Validator\Constraints\Recaptcha;
     
     $builder->add('recaptcha', RecaptchaSubmitType::class, [
         'constraints' => [
             new Recaptcha(),
         ],
     ]);
     

4. API Integration

   • Manually verify tokens via the service:

     $this->get('recaptcha.recaptcha')->verify($token);
     

Integration Tips

• Twig Integration: Use the recaptcha_widget function in templates:

  {{ form_widget(form.recaptcha) }}
  

• Dynamic Keys: Override keys per environment (e.g., recaptcha.yaml in config/{env}/).
• Error Handling: Customize error messages in RecaptchaSubmitType:

  ->add('recaptcha', RecaptchaSubmitType::class, [
      'error_bubbling' => true,
      'error_mapping' => [
          'recaptcha' => 'recaptcha.error',
      ],
  ])
  

Gotchas and Tips

Pitfalls

1. Key Mismatch

   • Ensure public_key and private_key match your Google reCAPTCHA settings. Test with the reCAPTCHA demo.
   • Debug: Check config/packages/recaptcha.yaml for typos.

2. Version Conflicts

   • The bundle assumes reCAPTCHA v2. If using v3, verify compatibility or switch packages (e.g., symfony/webpack-encore for v3).

3. CSRF Issues

   • If forms fail silently, ensure Symfony’s CSRF protection is enabled and reCAPTCHA tokens are submitted correctly.

4. Deprecated PHP

   • The package requires PHP 5.6+, but modern Laravel (8+) uses PHP 8+. Test thoroughly if using older PHP.

Debugging

• Logs: Enable debug mode (APP_DEBUG=true) to log reCAPTCHA API responses.
• Manual Verification: Test the API directly:

  $response = $this->get('recaptcha.recaptcha')->verify($token);
  dd($response->isSuccess()); // Should return true for valid tokens
  

Extension Points

1. Custom Services

   • Override the default service by binding your own RecaptchaInterface implementation:

     $this->app->bind(\Delatlantik\RecaptchaBundle\Service\RecaptchaInterface::class, CustomRecaptchaService::class);
     

2. Event Listeners

   • Listen to reCAPTCHA events (if the bundle emits them) to log or modify responses:

     $events->dispatch(new RecaptchaEvent($response));
     

3. Configuration Overrides

   • Extend recaptcha.yaml with custom options (e.g., score_threshold for v3):

     recaptcha:
         key: "public_key"
         secret: "private_key"
         options: { "score_threshold": 0.5 } # Example for v3
     

Tips

• Rate Limiting: Google may block excessive requests. Cache tokens or implement retries.
• Testing: Use the recaptcha:verify command or mock the service in tests:

  $this->mock(\Delatlantik\RecaptchaBundle\Service\RecaptchaInterface::class)
       ->shouldReceive('verify')
       ->andReturn(new Response(true, 'Success'));
  

• Local Development: Use Google’s test keys (6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI) to avoid hitting API limits.