Captcha Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require pakdel8463/aron-captcha
   

   Publish the config file:

   php artisan vendor:publish --provider="Pakdel8463\AronCaptcha\AronCaptchaServiceProvider" --tag="config"
   

2. Basic Usage Add the Captcha field to a form:

   <form method="POST" action="/submit">
       @csrf
       {!! captcha() !!}
       <!-- Your form fields -->
   </form>
   

3. Validation Validate the Captcha in your controller:

   use Pakdel8463\AronCaptcha\Facades\AronCaptcha;
   
   public function store(Request $request) {
       $request->validate([
           'captcha' => 'required|captcha',
       ]);
   
       // Proceed with form submission
   }
   

4. First Use Case Secure a contact form or registration page by adding Captcha to prevent spam.

Implementation Patterns

Common Workflows

1. Dynamic Captcha Generation Generate a new Captcha on demand (e.g., after a failed attempt):

   $captcha = AronCaptcha::generate();
   return view('form', ['captcha' => $captcha]);
   

2. Customizing Captcha Appearance Override default settings in config/aron-captcha.php:

   'width' => 200,
   'height' => 80,
   'length' => 6,
   'font_size' => 20,
   'colors' => ['background' => '#f5f5f5', 'text' => ['#000000', '#333333']],
   

3. Integration with Forms Use the Blade directive for simplicity:

   @captcha(['width' => 150, 'height' => 60])
   

   Or manually in JavaScript:

   fetch('/captcha/generate')
       .then(response => response.text())
       .then(data => {
           document.getElementById('captcha-container').innerHTML = data;
       });
   

4. API-Based Captcha For SPAs or APIs, use the endpoint:

   Route::get('/captcha/generate', [AronCaptchaController::class, 'generate']);
   

   Validate via:

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

5. Rate Limiting Combine with Laravel’s rate limiting middleware:

   Route::middleware(['throttle:5,1'])->group(function () {
       Route::post('/submit', [YourController::class, 'store']);
   });
   

Gotchas and Tips

Pitfalls and Debugging

1. Captcha Not Validating

   • Ensure the captcha rule is correctly imported (use Pakdel8463\AronCaptcha\Rules\Captcha;).
   • Check if the session key (captcha.storage) matches the validation rule.
   • Verify the Captcha image isn’t being cached aggressively by the browser (add a timestamp query string or cache-busting).

2. Session Storage Issues

   • The package stores Captcha data in the session. If using a custom session driver, ensure it’s properly configured.
   • Clear old Captcha entries manually if needed:

     AronCaptcha::clear();
     

3. Case Sensitivity

   • Validation is case-sensitive by default. Override in config:

     'case_sensitive' => false,
     

4. Performance with High Traffic

   • Regenerate Captcha on each request if spam is rampant (trade-off: user experience).
   • Consider caching the Captcha image (but ensure it’s invalidated on validation failure).

5. Custom Storage Backends Extend the package by binding a custom storage handler:

   AronCaptcha::extend('redis', function ($app) {
       return new \Pakdel8463\AronCaptcha\Storage\RedisStorage(
           $app->make('redis')
       );
   });
   

   Then use it in config:

   'driver' => 'redis',
   

Tips for Daily Use

1. Testing Mock the Captcha in tests:

   $this->partialMock(AronCaptcha::class, ['generate'])
        ->shouldReceive('generate')
        ->andReturn(['code' => 'TEST123']);
   

2. Accessibility Add a "refresh Captcha" button with ARIA labels:

   <button onclick="refreshCaptcha()" aria-label="Refresh CAPTCHA">
       <span>↻</span>
   </button>
   

3. Logging Failed Attempts Log invalid attempts to monitor abuse:

   try {
       $request->validate(['captcha' => 'required|captcha']);
   } catch (\Illuminate\Validation\ValidationException $e) {
       \Log::warning('Failed CAPTCHA attempt', ['ip' => $request->ip()]);
       throw $e;
   }
   

4. Theming Override the Blade view (resources/views/vendor/aron-captcha.blade.php) to match your app’s design.

5. Multi-Language Support Localize error messages in resources/lang/{locale}/validation.php:

   'captcha' => 'The CAPTCHA code is incorrect.',