README

Laravel Captcha is a modern, lightweight, and extensible CAPTCHA package for Laravel. It provides a flexible and developer-friendly way to generate and validate CAPTCHA images, with support for multiple drivers and configurations.

⚠️ This package is based primarily on the excellent mews/captcha package, with a redesigned architecture, improved testability, and modern Laravel support.

🚀 Features

• Simple and flexible CAPTCHA generation
• Multiple configurations (default, flat, mini, inverse, math)
• Support for GD and Imagick drivers
• API-friendly responses (Base64 image output)
• Built-in validation (session & API modes)
• Fully configurable:
  • Length
  • Fonts
  • Colors
  • Backgrounds
  • Effects (blur, sharpen, contrast, etc.)
• Math CAPTCHA support
• Laravel-native integration:
  • Service Provider
  • Facade
  • Helper functions
• Fully tested using Pest

📦 Requirements

• PHP >= 8.3
• Laravel 12.x or 13.x

❗ Other Laravel versions are not supported

📦 Installation

composer require achetibi/laravel-captcha

⚙️ Configuration

Publish the configuration file:

php artisan vendor:publish --provider="LaravelCaptcha\CaptchaServiceProvider"

🧠 Basic Usage

Generate CAPTCHA (HTML response)

captcha();

Generate CAPTCHA (API / Base64)

captcha('default');

Get CAPTCHA image URL

captcha_src();

Get CAPTCHA HTML image

captcha_img('default', ['class' => 'captcha']);

Validate CAPTCHA (session-based)

captcha_check($value);

Validate CAPTCHA (API-based)

captcha_api_check($value, $key);

Check CAPTCHA status

captcha_enabled();
captcha_disabled();

⚙️ Configuration Options

Example configuration:

'default' => [
    'length' => 6,
    'width' => 345,
    'height' => 65,
    'quality' => 90,
    'math' => false,
    'expire' => 60,
    'encrypt' => false,
],

🖼 Available Presets

• default
• flat
• mini
• inverse
• math

🖼 Image Drivers

The package supports two image drivers:

• GD (default)
• Imagick

Driver Configuration

CAPTCHA_DRIVER=gd

or

CAPTCHA_DRIVER=imagick

Driver Fallback

If imagick is selected but not installed, the package will automatically fallback to GD.

🧪 Testing

Run the test suite:

composer test

The package includes:

• Unit tests
• Feature tests
• Driver validation tests (GD / Imagick)
• Exception handling tests
• Helper and facade tests

🧱 Architecture

The package is structured around:

• Captcha core service
• Laravel Service Container binding
• Facade for convenient access
• Global helper functions

⚠️ Important Notes

• CAPTCHA is single-use (invalidated after validation)
• Cache is used for expiration handling
• Session is used for standard validation
• API mode does not rely on session

🔒 Security

• Values are hashed using Laravel’s Hash Manager
• Optional encryption using Laravel Crypt
• One-time validation prevents replay attacks

📌 Roadmap

• Multiple configurations
• GD / Imagick support
• API validation
• Full test coverage
• Custom driver support
• WebP / AVIF support
• Rate limiting integration

🙏 Credits

• Abderrahim CHETIBI
• mews/captcha
• All Contributors

📄 License

The MIT License (MIT). See LICENSE.md for full license text.