achetibi/laravel-captcha

Laravel Captcha Package

1.0.0 2026-04-15 23:29 UTC

Requires

• php: ^8.3
• ext-gd: *
• illuminate/config: ^12|^13
• illuminate/filesystem: ^12|^13
• illuminate/hashing: ^12|^13
• illuminate/http: ^12|^13
• illuminate/routing: ^12|^13
• illuminate/session: ^12|^13
• illuminate/support: ^12|^13
• intervention/image: ^3.7

Requires (Dev)

• laravel/pint: ^1.29
• orchestra/testbench: ^11.1
• pestphp/pest: ^4.6
• pestphp/pest-plugin-laravel: ^4.1
• pestphp/pest-plugin-type-coverage: ^4.0

MIT

• Abderrahim CHETIBI

• captcha
• Laravel Security
• Laravel Captcha

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.