Search by

azcaptcha / azcaptcha-php

AZcaptcha

Official AZcaptcha SDK for PHP — reCAPTCHA, hCaptcha, Turnstile and image captchas

Package info

github.com/AZcaptcha/azcaptcha-php

Homepage

pkg:composer/azcaptcha/azcaptcha-php

Statistics

Installs: 1

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-18 08:48 UTC

This package is auto-updated.

Last update: 2026-11-18 09:34:35 UTC


README

Official PHP client for AZcaptcha — image captchas, reCAPTCHA v2/v3, hCaptcha, Cloudflare Turnstile, FunCaptcha and GeeTest.

  • 2Captcha-compatible method surface (solve, result, balance, reportBad) plus the modern JSON API (createTask, getTaskResult).
  • Typed exceptions for every API error code (spec-v1.0.0).
  • Contract polling with NO_SLOT backoff and per-type deadlines.
  • No runtime dependencies beyond ext-curl and ext-json, PHP 7.4+.

Install

composer require azcaptcha/azcaptcha-php

Quickstart

use Azcaptcha\Client;

$client = new Client('YOUR_API_KEY');

// reCAPTCHA v2
$token = $client->solveRecaptchaV2(
    '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
    'https://example.com/login'
);

// Image captcha (file path, base64, data: URI or raw bytes)
$answer = $client->solveImage('captcha.png');

// hCaptcha / Turnstile
$token = $client->solveHCaptcha('SITEKEY', 'https://example.com/');
$token = $client->solveTurnstile('0x4AAAAAAA...', 'https://example.com/');

Low-level (2Captcha style)

$taskId = $client->submit('userrecaptcha', [
    'googlekey' => 'SITEKEY',
    'pageurl' => 'https://example.com/',
]);
$token = $client->waitResult($taskId, 300);  // polls 1s then every 5s

Modern JSON API

$taskId = $client->createTask('RecaptchaV2TaskProxyless', [
    'websiteURL' => 'https://example.com/login',
    'websiteKey' => 'SITEKEY',
]);
$solution = $client->waitTaskResult($taskId);
echo $solution['gRecaptchaResponse'];

Proxies

$client->solveRecaptchaV2($sitekey, $pageurl, false, false, [
    'proxy' => 'socks5://user:pass@1.2.3.4:1080',
]);

Any accepted spelling works (scheme://user:pass@host:port, host:port:user:pass, user:pass@host:port). The scheme is never sent upstream; proxytype is derived (http/https → HTTP, socks4, socks5).

Errors

use Azcaptcha\Exception\BalanceException;
use Azcaptcha\Exception\CapacityException;
use Azcaptcha\Exception\ResultException;

try {
    $token = $client->solveTurnstile($sitekey, $pageurl);
} catch (BalanceException $e) {
    // ERROR_ZERO_BALANCE
} catch (CapacityException $e) {
    // ERROR_NO_SLOT_AVAILABLE — retry with backoff
} catch (ResultException $e) {
    // unsolvable / timeout / expired
}

Every exception exposes $errorCode and $retryable. waitResult retries only codes marked retryable and backs off 10s ×1.5 up to 60s.

Timeouts

Defaults match server settings: image 120s, hCaptcha 120s, Turnstile 180s, reCAPTCHA and others 300s. Override per call: solve('turnstile', $params, 90) or waitResult($id, 600).

Custom transport

$client = new Client('KEY', 'https://azcaptcha.com', new MyTransport());

MyTransport implements Azcaptcha\Transport\TransportInterface.

Links

License

MIT — see LICENSE.