{"id":24981,"date":"2026-08-06T10:17:46","date_gmt":"2026-08-06T10:17:46","guid":{"rendered":"https:\/\/capskip.com\/?p=24981"},"modified":"2026-08-06T10:17:46","modified_gmt":"2026-08-06T10:17:46","slug":"recaptcha-v2-php","status":"publish","type":"post","link":"https:\/\/capskip.com\/zh\/recaptcha-v2-php\/","title":{"rendered":"\u5982\u4f55\u7528 PHP \u8bc6\u522b reCAPTCHA v2\uff08\u542b\u9690\u5f62\u7248\uff09"},"content":{"rendered":"

reCAPTCHA v2 has three variants, and in PHP they are one method with an options array. Checkbox is the bare call, Invisible and Enterprise are flags, and both can be set together. PHP is also the one CapSkip SDK with no async story at all, which simplifies the code but changes how you should structure bulk work.<\/p>\n

Setup<\/h2>\n
# PHP 8.0 or newer. Needs the curl and json extensions,\n# both of which ship with almost every PHP install.\ncomposer require capskip\/capskip<\/pre>\n
CapSkip solves on your own machine, so the desktop app has to be running. Point the client at the port from its settings:<\/p>\n
use CapSkip\\CapSkip;\n\n$solver = new CapSkip([\n    'apiKey' => 'capskip',        \/\/ any string when key validation is off\n    'host' => '127.0.0.1',\n    'port' => 8080,\n    'recaptchaTimeout' => 300,    \/\/ seconds\n]);<\/pre>\n
In production, read those from the environment:<\/p>\n
use CapSkip\\CapSkip;\n\n$solver = new CapSkip([\n    'apiKey' => getenv('CAPSKIP_API_KEY') ?: 'capskip',\n    'host' => getenv('CAPSKIP_HOST') ?: '127.0.0.1',\n    'port' => (int) (getenv('CAPSKIP_PORT') ?: 8080),\n]);<\/pre>\n
The three variants<\/h2>\n\n\n\n\n\n\n\n\n
Variant<\/th>\nOption to add<\/th>\n<\/tr>\n<\/thead>\n
Checkbox<\/td>\nnone<\/td>\n<\/tr>\n
Invisible<\/td>\n['invisible' => 1]<\/code><\/td>\n<\/tr>\n
Enterprise<\/td>\n['enterprise' => 1]<\/code><\/td>\n<\/tr>\n
Invisible Enterprise<\/td>\nboth keys<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
\/\/ Checkbox: sitekey and page URL only.\n$result = $solver->recaptcha(\n    '6Lc...YOUR_SITEKEY',\n    'https:\/\/example.com\/login'\n);\n\necho $result['code'];   \/\/ g-recaptcha-response token\n\n\/\/ Invisible.\n$result = $solver->recaptcha($sitekey, $pageUrl, ['invisible' => 1]);\n\n\/\/ Enterprise, and both together.\n$result = $solver->recaptcha($sitekey, $pageUrl, ['enterprise' => 1]);\n$result = $solver->recaptcha($sitekey, $pageUrl, [\n    'enterprise' => 1,\n    'invisible' => 1,\n]);<\/pre>\n
The return value is an associative array, so $result['code']<\/code> is the token. $result['captchaId']<\/code> is there too if you want to log which solve produced it.<\/p>\n
Getting the inputs right<\/h2>\n
The sitekey is the data-sitekey<\/code> attribute on the widget container, or the first argument to grecaptcha.render<\/code> when Invisible mode means there is no container to look at. It always starts with 6L<\/code> and is public.<\/p>\n
The URL must be the page the widget renders on. Passing your form handler or a post-login redirect is the usual cause of a token that solves fine and then fails verification.<\/p>\n
Submitting the token<\/h2>\n
$ch = curl_init('https:\/\/example.com\/login');\n\ncurl_setopt_array($ch, [\n    CURLOPT_POST => true,\n    CURLOPT_RETURNTRANSFER => true,\n    CURLOPT_POSTFIELDS => http_build_query([\n        'g-recaptcha-response' => $result['code'],\n        'username' => '...',\n        'password' => '...',\n    ]),\n]);\n\n$response = curl_exec($ch);\ncurl_close($ch);<\/pre>\n
Tokens are single use and last about two minutes, so solve as late in the flow as possible. If the site hands the token to a JavaScript callback instead of a form field, the solve is identical but submission differs. Our reCAPTCHA v2 callback solver<\/a> page covers that shape.<\/p>\n
Errors, and the namespace people miss<\/h2>\n
PHP puts its exceptions under their own namespace, which trips up anyone copying imports from the Python or Node examples:<\/p>\n
use CapSkip\\CapSkip;\nuse CapSkip\\Exceptions\\ValidationException;\nuse CapSkip\\Exceptions\\NetworkException;\nuse CapSkip\\Exceptions\\ApiException;\nuse CapSkip\\Exceptions\\TimeoutException;\n\ntry {\n    $result = $solver->recaptcha($sitekey, $pageUrl);\n} catch (ValidationException $e) {\n    \/\/ missing or malformed arguments\n} catch (NetworkException $e) {\n    \/\/ CapSkip is not running on the configured port\n} catch (ApiException $e) {\n    \/\/ the sitekey or pageurl was rejected\n} catch (TimeoutException $e) {\n    \/\/ exceeded recaptchaTimeout\n}<\/pre>\n
All four extend CapSkip\\Exceptions\\CapSkipError<\/code>, so a single catch on the base class handles everything if you would rather deal with failures in one place.<\/p>\n
Solving several<\/h2>\n
PHP executes synchronously, so each solve blocks until it finishes:<\/p>\n
use CapSkip\\CapSkip;\n\n$solver = new CapSkip();\n\nforeach ($targets as $target) {\n    $results[] = $solver->recaptcha($target['sitekey'], $target['url']);\n}<\/pre>\n
The package exports AsyncCapSkip<\/code>, but in PHP it is only an alias so that code ported from the other SDKs keeps running. It does not add concurrency. For genuine parallelism, run multiple worker processes or use a queue rather than expecting the SDK to overlap solves.<\/p>\n
Using a proxy<\/h2>\n
$result = $solver->recaptcha($sitekey, $pageUrl, [\n    'proxy' => ['type' => 'HTTPS', 'uri' => 'user:pass@1.2.3.4:3128'],\n]);<\/pre>\n
Proxies are supported for reCAPTCHA, Turnstile and GeeTest, but not for image CAPTCHAs, which are solved from the image bytes and never reach the target site.<\/p>\n
Frequently asked questions<\/h2>\n
\n\n
Do I need to poll for the result?<\/h3>\n<\/summary>\n
No. The SDK polls internally and returns the finished token, so CAPCHA_NOT_READY<\/code> never reaches your code. It begins checking after 250ms and backs off from there.<\/p>\n<\/details>\n
\n\n
Will a solve block my web request?<\/h3>\n<\/summary>\n
Yes, and that matters in PHP. A reCAPTCHA solve can take several seconds, so doing it inside a page render ties up a worker. Push solving into a queued job or a CLI worker rather than blocking a request thread.<\/p>\n<\/details>\n
\n\n
What are the requirements?<\/h3>\n<\/summary>\n
PHP 8.0 or newer with the curl<\/code> and json<\/code> extensions, both bundled with most installs. There are no other runtime dependencies, so it drops into an existing project without pulling a tree of packages.<\/p>\n<\/details>\n
Summary<\/h2>\n
One method, three variants, selected with invisible<\/code> and enterprise<\/code> in the options array. Read $result['code']<\/code>, submit it as g-recaptcha-response<\/code>, import exceptions from CapSkip\\Exceptions<\/code>, and keep solves off your request threads.<\/p>\n
The wider PHP surface is on the PHP CAPTCHA solver<\/a> page, other languages on the reCAPTCHA v2 solver<\/a> page, and there is a live v2 demo<\/a> to test against. CapSkip is a local captcha solver<\/a>, so nothing is billed per solve.<\/p>\n","protected":false},"excerpt":{"rendered":"
\u4e09\u79cd reCAPTCHA v2 \u53d8\u4f53\u90fd\u662f\u540c\u4e00\u4e2a PHP \u65b9\u6cd5\uff0c\u53ea\u662f\u6570\u7ec4\u9009\u9879\u4e0d\u540c\u3002\u4e0b\u9762\u9010\u4e00\u8bf4\u660e\uff0c\u8fd8\u6709\u4eba\u4eec\u5e38\u5ffd\u7565\u7684\u5f02\u5e38\u547d\u540d\u7a7a\u95f4\u3002<\/p>","protected":false},"author":1,"featured_media":24980,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"Solve reCAPTCHA v2 in PHP | CapSkip","rank_math_description":"Checkbox, Invisible and Enterprise are one PHP call with different options. Here is each variant, the exception namespace, and where the token has to go.","rank_math_focus_keyword":"solve recaptcha v2 in php","footnotes":""},"categories":[71],"tags":[],"class_list":["post-24981","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-google-recaptcha"],"_links":{"self":[{"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/posts\/24981","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/comments?post=24981"}],"version-history":[{"count":1,"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/posts\/24981\/revisions"}],"predecessor-version":[{"id":24996,"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/posts\/24981\/revisions\/24996"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/media\/24980"}],"wp:attachment":[{"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/media?parent=24981"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/categories?post=24981"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/capskip.com\/zh\/wp-json\/wp\/v2\/tags?post=24981"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}