Recaptcha Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require excelwebzone/recaptcha-bundle
   

   For Symfony 4/5, no AppKernel.php registration is needed—autoloading handles it.

2. Configuration: Add to config/packages/ewz_recaptcha.yaml:

   ewz_recaptcha:
       version: 3  # or 2
       site_key:   'YOUR_SITE_KEY'
       secret_key: 'YOUR_SECRET_KEY'
   

   For dev environments, override in config/packages/dev/ewz_recaptcha.yaml.

3. First Use Case: Add the Twig extension to a form template:

   {{ render_recaptcha('contact_form') }}
   

   Validate in a controller:

   use EWZ\Bundle\RecaptchaBundle\Validator\Constraints\Recaptcha;
   
   public function submitForm(Request $request) {
       $form = $this->createForm(...);
       $form->handleRequest($request);
   
       if ($form->isSubmitted() && $form->isValid()) {
           // Success
       }
   }
   

Implementation Patterns

Form Integration

1. Twig Integration: Use render_recaptcha() in templates with optional parameters:

   {{ render_recaptcha('form_name', {
       'theme': 'light',
       'size': 'compact',
       'type': 'image'  # v2 only
   }) }}
   

2. FormBuilder Integration: Add the constraint to a form field:

   $builder->add('submit', SubmitType::class, [
       'constraints' => [
           new Recaptcha([
               'version' => 3,
               'error_message' => 'Please verify you are not a robot.'
           ])
       ]
   ]);
   

3. Dynamic Configuration: Override settings per form/action via YAML:

   ewz_recaptcha:
       forms:
           contact_form:
               version: 3
               size: 'normal'
   

Workflows

1. Multi-Step Forms: Reuse the same site_key across steps but validate only on submission.

2. API/Non-Twig Use: Validate manually in controllers:

   $validator = $this->container->get('ewz_recaptcha.validator');
   $isValid = $validator->validate($request->request->get('g-recaptcha-response'));
   

3. Custom Error Handling: Extend the validator or override Twig error messages:

   {% if form.errors.hasError('submit', 'recaptcha') %}
       <div class="error">{{ form_errors(form.submit) }}</div>
   {% endif %}
   

Gotchas and Tips

Pitfalls

1. Version Mismatch:

   • v2 and v3 have different config keys (e.g., secret_key vs. secret).
   • v3 requires action in the frontend script (auto-handled by the bundle).

2. Caching Issues:

   • Clear cache after changing site_key/secret_key:

     php bin/console cache:clear
     

3. Dev Environment:

   • Use localhost in allowed_domains for testing (v3 only):

     ewz_recaptcha:
         allowed_domains: ['localhost', '127.0.0.1']
     

Debugging

1. Validation Failures:

   • Check Google’s test responses for debugging:
     • v2: 03AHJ2... (valid) vs. empty string (invalid).
     • v3: Non-empty JSON response (valid) vs. empty or invalid JSON.

2. Logs: Enable debug mode to log validation attempts:

   ewz_recaptcha:
       debug: true
   

Extension Points

1. Custom Validators: Extend EWZ\Bundle\RecaptchaBundle\Validator\RecaptchaValidator for custom logic.

2. Twig Extensions: Override render_recaptcha() in a custom Twig extension for theming.

3. Event Listeners: Subscribe to ewz_recaptcha.validate events for pre/post-validation hooks.

Pro Tips

• Rate Limiting: Use Google’s rate limits as a guide for form design.
• v3 Score Threshold: Adjust in config:

  ewz_recaptcha:
      version: 3
      score_threshold: 0.5  # Default is 0.9
  

• Multi-Language: Use hl parameter in Twig for language-specific prompts:

  {{ render_recaptcha('form', {'hl': 'es'}) }}