Easy Geetest Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require beastphp/easy-geetest
   

   Add the service provider in config/app.php under providers:

   Beastphp\EasyGeetest\EasyGeetestServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Beastphp\EasyGeetest\EasyGeetestServiceProvider"
   

   Update config/easy-geetest.php with your Geetest API keys (captcha_id, private_key, check_captcha_url).

3. First Use Case Verify a Geetest captcha response in a controller:

   use Beastphp\EasyGeetest\EasyGeetest;
   
   public function verifyCaptcha(Request $request)
   {
       $geetest = app(EasyGeetest::class);
       $result = $geetest->successVerify($request->all());
   
       if ($result) {
           return redirect()->route('dashboard');
       }
   
       return back()->withErrors(['captcha' => 'Verification failed']);
   }
   

Implementation Patterns

Common Workflows

1. Frontend Integration Include Geetest JS in your blade template:

   <script src="https://static.geetest.com/static/js/gt.js"></script>
   <script>
       initGeetest({
           gt: '{{ config('easy-geetest.gt') }}',
           challenge: '{{ $challenge }}',
           product: 'bind',
           offline: !checkOnlineStatus(),
       }, function(captchaObj) {
           // Handle captcha response
       });
   </script>
   

2. Backend Validation Use successVerify() for registration/login forms:

   $request->validate([
       'geetest_challenge' => 'required',
       'geetest_validate' => 'required',
       'geetest_seccode' => 'required',
   ]);
   
   $geetest = app(EasyGeetest::class);
   $result = $geetest->successVerify($request->only([
       'geetest_challenge',
       'geetest_validate',
       'geetest_seccode',
       'geetest_user_id',
   ]));
   

3. API Integration For API endpoints, use apiVerify():

   $result = $geetest->apiVerify([
       'challenge' => $request->challenge,
       'validate' => $request->validate,
       'seccode' => $request->seccode,
       'user_id' => $request->user_id,
   ]);
   

4. Rate Limiting Combine with Laravel’s throttle middleware:

   Route::post('/login', [LoginController::class, 'store'])
       ->middleware('throttle:5,1');
   

Integration Tips

• Laravel Forms: Use geetest package with Laravel Collective or Livewire for seamless integration.
• Caching: Cache the gt parameter (if static) to reduce API calls:

  $gt = Cache::remember('geetest_gt', now()->addHours(1), function() {
      return $geetest->getGt();
  });
  

• Testing: Mock the EasyGeetest facade in unit tests:

  $this->mock(EasyGeetest::class)->shouldReceive('successVerify')->andReturn(true);
  

Gotchas and Tips

Pitfalls

1. Deprecated Methods Avoid verify() (deprecated in favor of successVerify() or apiVerify()). The package lacks documentation for newer Geetest SDK features (e.g., v4+).

2. Key Exposure Hardcoding keys in .env is safe, but avoid logging $request->all() in production (it may leak private_key if misconfigured).

3. Timeouts Geetest’s check_captcha_url may time out. Increase Laravel’s timeout in config/caching.php if needed:

   'default' => env('REDIS_TIMEOUT', 2.5),
   

4. Offline Mode Geetest’s JS may fail in offline mode. Handle offline flag explicitly:

   offline: !navigator.onLine, // Custom offline check
   

Debugging

• Logs: Enable debug mode in config/easy-geetest.php:

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

  Logs will appear in storage/logs/laravel.log.

• Response Codes:

  • 1: Success.
  • 0: Failure (check geetest_error in response for details).
  • -1: Network error (verify check_captcha_url).

• Common Errors:

  • "Invalid challenge": Ensure geetest_challenge matches the frontend’s challenge parameter.
  • "Key mismatch": Verify captcha_id and private_key in config.

Extension Points

1. Custom Responses Extend the Beastphp\EasyGeetest\EasyGeetest class to add custom logic:

   class CustomGeetest extends EasyGeetest {
       public function customVerify(array $data) {
           $response = $this->callGeetestApi('custom_endpoint', $data);
           return $this->parseResponse($response);
       }
   }
   

2. Event Listeners Dispatch events for captcha success/failure:

   event(new CaptchaVerified($request->user, $result));
   

3. Middleware Create middleware to auto-verify captchas:

   public function handle($request, Closure $next) {
       if ($request->is('login') && !$this->verifyCaptcha($request)) {
           abort(422, 'Captcha verification failed');
       }
       return $next($request);
   }
   

4. Fallback Mechanisms Implement a fallback (e.g., hCaptcha) if Geetest fails:

   try {
       $result = $geetest->successVerify($data);
   } catch (\Exception $e) {
       $result = $this->fallbackVerify($data);
   }