README

👁 PHP Version
👁 License
👁 Build Status
👁 Coverage

English | 中文

A Symfony Bundle that provides image captcha functionality for website security protection.

Features

• Generate random captcha codes and store challenge values in cache
• Provide image captcha generation and display
• Provide captcha verification and one-time consumption functionality
• Support JSON-RPC interface

Installation

Install via Composer:

composer require tourze/captcha-challenge-bundle

Configuration

Register the Bundle in your Symfony application:

// config/bundles.php
return [
 // ...
 Tourze\CaptchaChallengeBundle\CaptchaChallengeBundle::class => ['all' => true],
];

Ensure environment variables are configured:

# .env
LOGIN_CHALLENGE_TYPE=captcha # Enable captcha functionality, set to 'null' to disable

Usage

Generating Captcha and Getting Image

// In your controller
use Tourze\CaptchaChallengeBundle\Service\ChallengeService;

class YourController extends AbstractController
{
 public function generateCaptcha(ChallengeService $challengeService): Response
 {
 // Generate captcha
 $challengeKey = $challengeService->generateChallenge();
 
 // Get captcha image URL
 $imageUrl = $challengeService->generateChallengeCaptchaImageUrl($challengeKey);
 
 return $this->json([
 'challengeKey' => $challengeKey,
 'imageUrl' => $imageUrl,
 ]);
 }
}

Verifying User Input Captcha

// In your controller
use Tourze\CaptchaChallengeBundle\Service\ChallengeService;

class YourController extends AbstractController
{
 public function verifyCode(
 Request $request,
 ChallengeService $challengeService
 ): Response
 {
 $challengeKey = $request->request->get('challengeKey');
 $userInput = $request->request->get('captchaCode');
 
 // Verify and consume captcha
 $isValid = $challengeService->checkAndConsume($challengeKey, $userInput);
 
 if (!$isValid) {
 return $this->json(['success' => false, 'message' => 'Invalid captcha code']);
 }
 
 return $this->json(['success' => true]);
 }
}

Advanced Usage

Custom Captcha Configuration

// Custom captcha generation with specific settings
$challengeKey = $challengeService->generateChallenge();

// Generate image with custom parameters
$imageUrl = $challengeService->generateChallengeCaptchaImageUrl($challengeKey);

Integration with Forms

// In your form type
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;

$builder
 ->add('challengeKey', HiddenType::class)
 ->add('captchaCode', TextType::class, [
 'label' => 'Enter captcha code',
 'required' => true,
 ]);

Technical Details

• Captcha uses 5-digit random numbers
• Captcha is stored in cache for 5 minutes
• After successful verification, it is immediately deleted from cache to prevent reuse
• Uses GD library to generate images, supports anti-OCR functionality

Requirements

• PHP 8.1+
• GD extension
• Symfony 6.4 framework
• PSR-16 cache implementation
• Gregwar/Captcha library

License

This Bundle is licensed under the MIT License. See the LICENSE file for details.