- How do I integrate gregwar/captcha with Laravel’s built-in validation system?
- Use Laravel’s Validator to check CAPTCHA input by creating a custom validation rule. Instantiate `CaptchaBuilder` and call `testPhrase()` on user input. For example, add a rule like `['captcha' => ['required', function($value) { $builder->testPhrase($value); }]]` to your validation array. Store the generated phrase in the session for comparison.
- Does gregwar/captcha work with Laravel 10 and PHP 8.2?
- Yes, gregwar/captcha is fully compatible with Laravel 10 and PHP 8.2. The package leverages PHP’s native `random_int()` for cryptographic security, which is supported in these versions. For older Laravel versions (e.g., 9.x on PHP 8.1), ensure no deprecated methods like `ImageFileHandler` are used, as they were removed in v2.0.0.
- Can I generate CAPTCHAs resistant to OCR scanning in Laravel?
- Yes, use the `buildAgainstOCR()` method to generate CAPTCHAs that are intentionally unreadable by OCR tools like `ocrad`. This requires the `imagemagick` and `ocrad` tools to be installed on your server. Call this method before `build()` to ensure OCR resistance. Note that this adds slight overhead due to shell execution.
- How do I create a reusable Blade directive for CAPTCHA generation?
- Register a custom Blade directive in a service provider. Use `Blade::directive('captcha', function() { $builder = new CaptchaBuilder(); $_SESSION['captcha_phrase'] = $builder->getPhrase(); return '<?php echo '.$builder->inline().'; ?>'; })`. Then, in your Blade template, use `@captcha` to generate and embed the CAPTCHA inline. This centralizes CAPTCHA logic and reduces repetition.
- What are the performance implications of using gregwar/captcha in production?
- gregwar/captcha adds minimal overhead—typically **5–10ms** per CAPTCHA generation when using cryptographic randomness (`random_int()`). This is negligible for most Laravel applications. For high-traffic sites, consider caching phrases per user session if deterministic behavior is acceptable for non-critical forms. Always benchmark with `microtime(true)` to validate performance.
- How do I handle CAPTCHA failures gracefully in Laravel forms?
- Return a validation error when `testPhrase()` fails. For example, use `$fail('CAPTCHA verification failed.')` in your custom validation rule. To improve UX, limit retry attempts (e.g., 3) and provide feedback like 'CAPTCHA expired; please refresh.' Store the phrase in the session with a timestamp to enforce expiration aligned with Laravel’s `session.lifetime`.
- Are there alternatives to gregwar/captcha for Laravel CAPTCHA generation?
- Yes, alternatives include `laravel-captcha` (a Laravel-specific wrapper) and `mathiasbynens/simple-captcha`. However, gregwar/captcha stands out for its **cryptographic security** (using `random_int()`) and OCR resistance. If you need a simpler solution, `mathiasbynens/simple-captcha` is lightweight but lacks advanced distortion features. For compliance-heavy projects, gregwar/captcha is the safer choice.
- How do I configure gregwar/captcha for high-security forms like admin logins?
- Prioritize cryptographic security by enabling distortion (`setDistortion(true)`) and using `buildAgainstOCR()` if OCR resistance is critical. Store the phrase in the session with a short expiry (e.g., 5 minutes) and log generation/failure events using Laravel’s `Log` facade. For extra security, combine with Laravel’s `throttle` middleware to limit CAPTCHA attempts.
- Does gregwar/captcha support custom fonts or background images?
- Yes, you can specify custom fonts via the `build()` method’s `$font` parameter. For background images, use `setBackgroundImages([$imagePath1, $imagePath2])`. However, disable distortion effects (e.g., `ignore_all_distortions()`) when using custom backgrounds to avoid visual conflicts. Test thoroughly to ensure compatibility with your design.
- How do I test gregwar/captcha in a Laravel CI/CD pipeline?
- Mock the `CaptchaBuilder` in unit tests using Laravel’s `Mockery` or PHPUnit. Verify `getPhrase()` and `testPhrase()` methods with predefined values. For integration tests, simulate user input and validate session storage. Use `Artisan::call()` to test CAPTCHA generation commands. Ensure your CI environment has the GD extension enabled, as it’s required for image generation.