Laravel Captcha Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require mydaniel/laravel-captcha
   

   Publish the config file (optional but recommended for customization):

   php artisan vendor:publish --provider="MyDaniel\Captcha\CaptchaServiceProvider"
   

2. First Use Case: Basic Text Captcha Add the captcha to a form in your Blade template:

   {!! captcha() !!}
   

   Validate the submission in your controller:

   use MyDaniel\Captcha\Rules\Captcha as CaptchaRule;
   
   $request->validate([
       'captcha' => [new CaptchaRule],
   ]);
   

3. Where to Look First

   • Config File: config/captcha.php (for customization).
   • Facade: Captcha::generate() (for dynamic generation).
   • Validation Rule: MyDaniel\Captcha\Rules\Captcha (for form validation).

Implementation Patterns

Core Workflows

1. Form Protection

   • Blade Integration:

     {!! captcha(['type' => 'math', 'length' => 5]) !!}
     

   • Validation:

     $request->validate(['captcha' => new CaptchaRule]);
     

2. Dynamic Generation Use the facade to generate captchas programmatically:

   $captcha = Captcha::generate('text', ['length' => 6]);
   return response()->json(['captcha' => $captcha]);
   

3. API Endpoints Secure API endpoints with captchas:

   public function store(Request $request) {
       $request->validate([
           'captcha' => new CaptchaRule,
           'data' => 'required'
       ]);
       // Process data...
   }
   

4. Custom Generators Extend the package by creating a new generator:

   use MyDaniel\Captcha\Contracts\Generator;
   
   class CustomGenerator implements Generator {
       public function generate(): string { /* ... */ }
   }
   

   Register it in config/captcha.php:

   'generators' => [
       'custom' => \App\Generators\CustomGenerator::class,
   ],
   

5. Multi-Language Validation Override validation messages in your language files:

   'validation' => [
       'captcha' => 'The captcha does not match.',
   ],
   

Gotchas and Tips

Pitfalls and Debugging

1. Captcha Not Showing?

   • Ensure the captcha facade is registered in config/app.php under aliases.
   • Check if the CaptchaServiceProvider is registered in config/app.php under providers.

2. Validation Failing Silently

   • Verify the captcha field name matches the one generated in the form (default: captcha).
   • Check for typos in the generator type (e.g., 'text' vs 'math').

3. Replay Attacks

   • The package uses one-time-use keys by default. If testing locally, ensure you’re not reusing the same captcha in multiple requests.
   • Adjust expiration_time in config/captcha.php for testing:

     'expiration_time' => 60 * 5, // 5 minutes
     

4. Image Distortion Issues

   • If captchas appear too distorted, tweak distortion_level in the config:

     'generators' => [
         'text' => [
             'distortion_level' => 0.3, // Lower = less distortion
         ],
     ],
     

Extension Points

1. Custom Validation Logic Extend the CaptchaRule class to add custom logic:

   use MyDaniel\Captcha\Rules\Captcha as BaseCaptchaRule;
   
   class CustomCaptchaRule extends BaseCaptchaRule {
       public function passes($attribute, $value) {
           // Custom logic...
           return parent::passes($attribute, $value);
       }
   }
   

2. Storage Backend Override the default storage (e.g., switch from session to Redis):

   'storage' => [
       'driver' => 'redis',
       'connection' => 'cache',
   ],
   

3. Event Listeners Listen for captcha generation/validation events:

   use MyDaniel\Captcha\Events\CaptchaGenerated;
   
   CaptchaGenerated::listen(function ($event) {
       Log::info('Captcha generated: ' . $event->captcha);
   });
   

Performance Tips

• Cache Generators: If using the same captcha type frequently, cache the generator instance:

  $generator = app(MyDaniel\Captcha\Generators\TextGenerator::class);
  

• Reduce Distortion: Lower distortion_level for better performance (but less security).
• Use Math Captchas for APIs: Math captchas are harder for bots to solve but easier for humans, making them ideal for API endpoints.

Configuration Quirks

• Case Sensitivity: Generator types ('text', 'math') are case-sensitive.
• Default Values: If no config is published, defaults are used (e.g., length = 6, expiration_time = 600 seconds).
• Session Dependency: The package relies on Laravel’s session. Ensure SESSION_DRIVER is set in .env (e.g., SESSION_DRIVER=file for testing).