Arcaptcha Laravel Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require mohammadv184/arcaptcha-laravel
   

2. Publish config (optional but recommended):

   php artisan vendor:publish --provider="Mohammadv184\Arcaptcha\ArcaptchaServiceProvider"
   

3. Add ArCaptcha to a Blade view:

   {!! ArCaptcha::render() !!}
   

4. Add validation rule to your form request or controller:

   $request->validate([
       'arcaptcha' => 'required|captcha'
   ]);
   

First Use Case

Contact Form Protection

• Embed ArCaptcha::render() in your contact form Blade template.
• Validate the submission with captcha rule.
• No API keys or external services needed—works out-of-the-box with the PHP library.

Implementation Patterns

Workflows

1. Blade Integration

   • Use ArCaptcha::render() in forms to generate the CAPTCHA widget.
   • Customize appearance via config (e.g., background, width, height).

   <div class="arcaptcha-container">
       {!! ArCaptcha::render(['background' => '#f5f5f5']) !!}
   </div>
   

2. Form Submission

   • Validate submissions with the captcha rule:

     use Illuminate\Support\Facades\Validator;
     
     $validator = Validator::make($request->all(), [
         'arcaptcha' => 'required|captcha',
     ]);
     

   • For API routes, use Arcaptcha::verify($token):

     if (!Arcaptcha::verify($request->input('arcaptcha'))) {
         return response()->json(['error' => 'Invalid CAPTCHA'], 422);
     }
     

3. Dynamic Rendering

   • Regenerate CAPTCHA on demand (e.g., after failed attempts):

     $newToken = ArCaptcha::generate();
     return view('form')->with(['arcaptcha_token' => $newToken]);
     

Integration Tips

• Laravel Validation: Pair with sometimes for conditional validation:

  $request->validate([
      'arcaptcha' => 'required_if:spam_protection,true|captcha',
  ]);
  

• Rate Limiting: Combine with Laravel’s throttle middleware to prevent brute-force attacks.
• Testing: Mock Arcaptcha::verify() in PHPUnit:

  Arcaptcha::shouldReceive('verify')->once()->andReturn(true);
  

Gotchas and Tips

Pitfalls

1. Token Mismatch

   • Ensure the token from the form (arcaptcha field) matches the server-side token.
   • Debug with:

     dd($request->input('arcaptcha'), ArCaptcha::getToken());
     

   • Fix: Regenerate the token if tokens don’t align (e.g., after form reload).

2. Configuration Overrides

   • Published config (config/arcaptcha.php) takes precedence over defaults.
   • Tip: Use config(['arcaptcha.width' => 300]) for runtime overrides.

3. Case Sensitivity

   • The validation rule (captcha) is case-sensitive. Use lowercase in rules.

4. Caching Issues

   • ArCaptcha tokens are stored in session. Clear session data if testing locally:

     session()->flush();
     

Debugging

• Enable Debug Mode: Add to config/arcaptcha.php:

  'debug' => env('ARCAPTCHA_DEBUG', false),
  

  Logs errors to storage/logs/laravel.log.

• Check Token Storage: Verify tokens are stored in session('arcaptcha.token').

Extension Points

1. Custom Error Messages Override validation messages in resources/lang/en/validation.php:

   'captcha' => 'The CAPTCHA verification failed. Please try again.',
   

2. Extend ArCaptcha Class Bind a custom service provider to modify behavior:

   // app/Providers/ArcaptchaServiceProvider.php
   public function register()
   {
       $this->app->bind('arcaptcha', function () {
           return new CustomArcaptcha();
       });
   }
   

3. Theme Customization Extend the Arcaptcha class to support themes:

   // app/Extensions/CustomArcaptcha.php
   class CustomArcaptcha extends \Mohammadv184\Arcaptcha\Arcaptcha
   {
       public function render(array $options = [])
       {
           $options['theme'] = 'dark';
           return parent::render($options);
       }
   }
   

Performance

• Token Regeneration: Avoid regenerating tokens unnecessarily (e.g., on every page load). Regenerate only when needed (e.g., form submission).
• Caching: For high-traffic sites, cache the CAPTCHA image (though this reduces security slightly). Use Laravel’s Cache facade:

  $cachedImage = Cache::remember('arcaptcha_image', 300, function () {
      return ArCaptcha::render();
  });