README

Lightweight, framework-agnostic captcha utility for PHP 8.3+.
Provides a pluggable algorithm/validation interface and optional session storage for user verification.

📦 Installation

composer require tetthys/captcha

Requires PHP 8.3+ (no helpers, no external dependencies).

🚀 Quick Example (Standalone PHP)

use Tetthys\Captcha\Algorithms\SimpleMathCaptcha;
use Tetthys\Captcha\Services\CaptchaService;
use Tetthys\Captcha\Services\CaptchaSession;

$service = new CaptchaService(
    new SimpleMathCaptcha(),
    new CaptchaSession(),
);

// Generate a new captcha
$captcha = $service->new();
echo $captcha->question; // e.g. "3 + 5 = ?"

// Later...
$userInput = '8';
$isValid = $service->validateCurrent($userInput); // true or false

🧩 Core Concepts

`CaptchaAlgorithmInterface`

Defines how a captcha is generated.

interface CaptchaAlgorithmInterface
{
    public function generate(): object; // { question, answer }
}

Example implementation:

(new SimpleMathCaptcha())->generate();
// => (object) [ 'question' => '7 + 2 = ?', 'answer' => '9' ]

`CaptchaValidatorInterface`

Defines how to check correctness.

interface CaptchaValidatorInterface
{
    public function validate(string $answer, string $input): bool;
}

`CaptchaSession`

Handles temporary storage of the correct answer. Uses Laravel’s session() helper if available, otherwise falls back to a simple array/object store.

$session = new CaptchaSession();
$session->set('42');
echo $session->pull(); // '42' (and then removed)

`CaptchaService`

Coordinates generation, storage, and validation.

$service = new CaptchaService(
    new SimpleMathCaptcha(),
    new CaptchaSession(),
);

$q = $service->new();                // -> question only
$isValid = $service->validateCurrent('7'); // checks user input vs stored answer

⚙️ Integration with Laravel

Add a simple service provider:

use Illuminate\Support\ServiceProvider;
use Tetthys\Captcha\Algorithms\SimpleMathCaptcha;
use Tetthys\Captcha\Services\CaptchaService;
use Tetthys\Captcha\Services\CaptchaSession;

final class CaptchaServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(CaptchaService::class, function () {
            return new CaptchaService(
                new SimpleMathCaptcha(),
                new CaptchaSession(),
            );
        });
    }
}

Laravel 11/12: bootstrap/app.php
Laravel 10: config/app.php → providers[]

Usage in controller:

$captcha = app(CaptchaService::class)->new();        // -> { question }
$isValid = app(CaptchaService::class)->validateCurrent($request->input('captcha'));

🧪 Custom Algorithms

You can easily define your own captcha generator:

use Tetthys\Captcha\Contracts\CaptchaAlgorithmInterface;

final class WordCaptcha implements CaptchaAlgorithmInterface
{
    public function generate(): object
    {
        $word = substr(str_shuffle('ABCDEFGHJKLMNPQRSTUVWXYZ'), 0, 5);
        return (object) ['question' => $word, 'answer' => $word];
    }
}

Swap it in:

new CaptchaService(new WordCaptcha(), new CaptchaSession());

🧮 Example API Response

GET /api/captcha
→ { "question": "4 + 6 = ?" }

POST /api/captcha
body: { "input": "10" }
→ { "valid": true }

tetthys / captcha

Maintainers

Details