Arcaptcha Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mohammadv184/arcaptcha
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Mohammadv184\Arcaptcha\ArcaptchaServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

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

   Update config/arcaptcha.php with your ArCaptcha API keys and site settings.

3. First Use Case: Basic Verification

   use Mohammadv184\Arcaptcha\Facades\Arcaptcha;
   
   $token = request('arcaptcha-token');
   $result = Arcaptcha::verify($token);
   
   if ($result) {
       // Valid CAPTCHA, proceed with form submission
   } else {
       // Invalid CAPTCHA, show error
   }
   

4. Blade Integration Add the CAPTCHA widget to your form:

   {!! Arcaptcha::render() !!}
   

Implementation Patterns

Common Workflows

1. Form Submission Validation Integrate with Laravel's validation pipeline:

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

   (Ensure the ArcaptchaRule is registered in AppServiceProvider.)

2. Dynamic CAPTCHA Rendering Customize CAPTCHA appearance via config:

   Arcaptcha::render([
       'theme' => 'dark',
       'size' => 'compact',
   ]);
   

3. API Endpoint Protection Protect API routes with CAPTCHA:

   Route::post('/api/submit', function () {
       $token = request('arcaptcha-token');
       if (!Arcaptcha::verify($token)) {
           return response()->json(['error' => 'Invalid CAPTCHA'], 403);
       }
       // Proceed with API logic
   });
   

4. Rate Limiting Integration Combine with Laravel's rate limiting:

   Route::middleware(['throttle:60,1', 'arcaptcha'])->group(function () {
       // Rate-limited and CAPTCHA-protected routes
   });
   

5. Custom Error Handling Override default error messages:

   Arcaptcha::setErrorMessage('custom.error.message');
   

Integration Tips

• Laravel Mix/Webpack: Bundle CAPTCHA assets if using custom themes.
• Caching: Cache verified tokens (if allowed by ArCaptcha's terms) to reduce API calls.
• Testing: Use Arcaptcha::fake() in tests to simulate valid/invalid responses:

  Arcaptcha::fake(['valid' => true]); // or false
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never commit config/arcaptcha.php to version control. Use environment variables:

     ARCAPTCHA_SITE_KEY=your_site_key
     ARCAPTCHA_SECRET_KEY=your_secret_key
     

2. Token Expiry

   • ArCaptcha tokens expire after 2 minutes. Ensure your form submission is fast or guide users to complete the CAPTCHA early.

3. CSRF Conflicts

   • If using Laravel's CSRF protection, ensure the CAPTCHA token field is excluded from CSRF checks or use csrf_exclude middleware.

4. Deprecated Methods

   • The package is last updated in 2021. Check for breaking changes if ArCaptcha's API evolves.

5. Network Errors

   • Handle connection issues gracefully:

     try {
         $result = Arcaptcha::verify($token);
     } catch (\Exception $e) {
         // Log error, show fallback CAPTCHA or manual verification
     }
     

Debugging Tips

• Enable Debug Mode Set debug to true in config/arcaptcha.php to log API responses.

• Manual Verification Test tokens via ArCaptcha's demo page to isolate issues.

• HTTP Client Inspection Override the HTTP client for debugging:

  Arcaptcha::setClient(new \GuzzleHttp\Client(['debug' => true]));
  

Extension Points

1. Custom Themes Extend the ArcaptchaServiceProvider to add theme support:

   public function boot()
   {
       Arcaptcha::extend('custom-theme', function () {
           return '<div class="custom-captcha">...</div>';
       });
   }
   

2. Event Listeners Listen for CAPTCHA events (if the package emits them):

   Arcaptcha::verified(function ($token) {
       // Log successful verifications
   });
   

3. Fallback Mechanisms Implement a fallback (e.g., simple text CAPTCHA) if ArCaptcha fails:

   if (!Arcaptcha::verify($token)) {
       return view('fallback-captcha');
   }
   

4. Multi-Site Support Use config groups to manage multiple ArCaptcha sites:

   Arcaptcha::setSite('secondary-site')->verify($token);