captchala/captchala-php

Captchala Server SDK for PHP - Validate captcha tokens server-side

dev-main 2026-02-04 20:11 UTC

Requires

• php: >=8.0
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^9.5 || ^10.0

MIT

• Captchala

• security
• validation
• captcha
• bot-protection

README

Server-side SDK for validating Captcha tokens.

中文文档

Installation

composer require captchala/captchala-php

Quick Start

<?php

use Captchala\Client;

// Create client
$client = new Client('your_app_key', 'your_app_secret');

// Validate token
$result = $client->validate($token);

if ($result->isValid()) {
    // Verification passed
    if ($result->isOffline()) {
        // Offline verification - may need additional risk control
    }
} else {
    // Verification failed
    echo $result->getError();
}

API Reference

Client::__construct(string $appKey, string $appSecret, int $timeout = 5)

Create a client instance.

• $appKey - App Key (from dashboard)
• $appSecret - App Secret (from dashboard)
• $timeout - Request timeout in seconds (default: 5)

Client::validate(string $token, bool $keepToken = false): ValidateResult

Validate a token.

• $token - The pass_token from frontend SDK
• $keepToken - If true, token won't be consumed (can be validated again)

ValidateResult Methods

Method	Return Type	Description
isValid()	bool	Whether validation passed
isOffline()	bool	Whether this was offline verification
isClientOnly()	bool	Whether this is a client-only token
getError()	?string	Get error message
getWarning()	?string	Get warning message
getChallengeId()	?string	Get challenge ID
getAction()	?string	Get business action
toArray()	array	Convert to array

Token Types

Prefix	Source	Security Level
pt_	Main API	High
offline_	Backup Service	Medium
client_	Client-only	Low (cannot verify server-side)

Complete Example

<?php

use Captchala\Client;

// Validation in login/register scenarios
function handleLogin(array $data): bool
{
    $client = new Client(
        getenv('CAPTCHALA_APP_KEY'),
        getenv('CAPTCHALA_APP_SECRET')
    );

    $result = $client->validate($data['captcha_token']);

    if (!$result->isValid()) {
        throw new Exception('Captcha verification failed: ' . $result->getError());
    }

    // Additional risk control for offline verification
    if ($result->isOffline()) {
        // Log for monitoring
        error_log('Offline captcha verification: ' . json_encode($result->toArray()));

        // Optional: Restrict sensitive operations for client-only tokens
        if ($result->isClientOnly()) {
            // Add extra verification or limit sensitive operations
        }
    }

    // Continue with login logic...
    return true;
}

Laravel Integration

<?php

namespace App\Http\Middleware;

use Closure;
use Captchala\Client;

class ValidateCaptcha
{
    private Client $captcha;

    public function __construct()
    {
        $this->captcha = new Client(
            config('services.captchala.key'),
            config('services.captchala.secret')
        );
    }

    public function handle($request, Closure $next)
    {
        $token = $request->input('captcha_token');

        if (!$token) {
            return response()->json(['error' => 'missing_captcha_token'], 400);
        }

        $result = $this->captcha->validate($token);

        if (!$result->isValid()) {
            return response()->json([
                'error' => 'captcha_failed',
                'message' => $result->getError(),
            ], 400);
        }

        // Store for later use
        $request->attributes->set('captcha_offline', $result->isOffline());
        $request->attributes->set('captcha_client_only', $result->isClientOnly());

        return $next($request);
    }
}

Testing

# Install dependencies
composer install

# Run tests
composer test

# Integration tests (requires real credentials)
CAPTCHALA_APP_KEY=xxx CAPTCHALA_APP_SECRET=xxx composer test

License

MIT