README

A PHP library that bypasses Cloudflare's anti-bot protection, including JavaScript challenges (V1, V2, V3) and Turnstile CAPTCHA. Port of the Python cloudscraper library.

Requirements

PHP >= 8.1
cURL extension
Node.js (for JavaScript challenge solving) or V8Js PHP extension
Composer

Installation

composer require cloudscraper/cloudscraper-php

Quick Start

<?php

use CloudScraper\CloudScraper;

$scraper = CloudScraper::create();

// GET request
$response = $scraper->get('https://example.com');
echo $response->getBody()->getContents();

// POST request
$response = $scraper->post('https://example.com/api', [
    'json' => ['key' => 'value'],
]);

Configuration

All options are passed via the create() factory method:

$scraper = CloudScraper::create([
    'debug'               => false,
    'interpreter'         => 'nodejs',     // 'nodejs' or 'v8js'
    'browser'             => ['browser' => 'chrome', 'platform' => 'windows', 'desktop' => true],
    'delay'               => null,         // Custom delay before challenge submission (seconds)
    'solveDepth'          => 3,            // Max recursive solve attempts
    'enable_stealth'      => true,
    'rotate_tls_ciphers'  => true,
    'ecdhCurve'           => 'prime256v1',
]);

Full Options Reference

Option	Type	Default	Description
`debug`	bool	`false`	Enable detailed logging
`interpreter`	string	`'nodejs'`	JS interpreter: `'nodejs'` or `'v8js'`
`browser`	array\|null	`null`	UA config: `browser`, `platform`, `desktop`, `mobile`, `custom`
`delay`	float\|null	`null`	Delay in seconds before submitting challenge solution
`solveDepth`	int	`3`	Maximum recursive challenge-solving depth
`captcha`	array	`[]`	Captcha provider config (`provider`, `api_key`)
`enable_stealth`	bool	`true`	Enable anti-fingerprinting stealth mode
`stealth_options`	array	`[]`	Stealth mode options
`rotate_tls_ciphers`	bool	`true`	Rotate TLS cipher suites between requests
`ecdhCurve`	string	`'prime256v1'`	ECDH curve for TLS
`rotating_proxies`	array\|null	`null`	List of proxy URLs for rotation
`proxy_options`	array	`[]`	Proxy rotation strategy options
`requestPreHook`	callable\|null	`null`	Hook called before each request
`requestPostHook`	callable\|null	`null`	Hook called after each request
`session_refresh_interval`	int	`3600`	Session refresh interval in seconds
`auto_refresh_on_403`	bool	`true`	Auto-refresh session on 403 responses
`max_403_retries`	int	`3`	Maximum 403 auto-retry attempts
`min_request_interval`	float	`1.0`	Minimum seconds between requests
`doubleDown`	bool	`true`	Re-request before V1 challenge solve
`disableCloudflareV1`	bool	`false`	Disable V1 challenge handler
`disableCloudflareV2`	bool	`false`	Disable V2 challenge handler
`disableCloudflareV3`	bool	`false`	Disable V3 challenge handler
`disableTurnstile`	bool	`false`	Disable Turnstile handler

CAPTCHA Providers

For sites using Cloudflare Turnstile or CAPTCHA challenges, configure an external solver:

$scraper = CloudScraper::create([
    'captcha' => [
        'provider' => '2captcha',   // '2captcha', 'anticaptcha', 'capsolver', 'capmonster'
        'api_key'  => 'YOUR_API_KEY',
    ],
]);

Supported Providers

Provider	Key	API Endpoint
2Captcha	`2captcha`	2captcha.com
Anti-Captcha	`anticaptcha`	api.anti-captcha.com
CapSolver	`capsolver`	api.capsolver.com
CapMonster	`capmonster`	api.capmonster.cloud

Proxy Rotation

$scraper = CloudScraper::create([
    'rotating_proxies' => [
        'http://user:pass@proxy1.example.com:8080',
        'http://user:pass@proxy2.example.com:8080',
        'socks5://proxy3.example.com:1080',
    ],
    'proxy_options' => [
        'strategy' => 'smart',   // 'sequential', 'random', or 'smart'
        'ban_time'  => 300,      // Seconds to ban a failed proxy
    ],
]);

The smart strategy tracks success/failure rates per proxy and favors proxies with higher success rates.

Stealth Mode

Stealth mode is enabled by default and applies:

Human-like delays: Random delays (0.5–2.0s) between requests
Header randomization: Varies Accept, Accept-Language, and DNT headers
Browser quirks: Adds browser-specific headers (Chrome's sec-ch-ua, Firefox's Upgrade-Insecure-Requests)
Header ordering: Reorders headers to match real browser order

Disable or customize:

$scraper = CloudScraper::create([
    'enable_stealth' => false,
]);

Extracting Tokens

Get Cloudflare clearance cookies for use with other HTTP clients:

// Returns [cookies_array, user_agent]
[$cookies, $userAgent] = CloudScraper::getTokens('https://example.com');

// Returns [cookie_string, user_agent]
[$cookieString, $userAgent] = CloudScraper::getCookieString('https://example.com');

Session Persistence

Serialize and restore scraper sessions:

// Save
$data = serialize($scraper);

// Restore
$scraper = unserialize($data);

Architecture

src/
├── CloudScraper.php              # Main class — wraps GuzzleHttp\Client
├── UserAgentManager.php          # UA selection and header management
├── CipherSuiteConfigurator.php   # TLS fingerprinting via cURL options
├── StealthMode.php               # Anti-detection techniques
├── ProxyManager.php              # Proxy rotation with strategies
├── SessionHealthMonitor.php      # Session refresh and throttling
├── Challenge/
│   ├── ChallengeDetectorInterface.php
│   ├── ChallengeHandlerInterface.php
│   ├── CloudflareV1Handler.php   # IUAM classic JS challenge
│   ├── CloudflareV2Handler.php   # Challenge Platform orchestrate
│   ├── CloudflareV3Handler.php   # JS VM challenge
│   └── TurnstileHandler.php      # Cloudflare Turnstile
├── Captcha/
│   ├── CaptchaSolverInterface.php
│   ├── CaptchaSolverFactory.php
│   ├── TwoCaptchaSolver.php
│   ├── AntiCaptchaSolver.php
│   ├── CapSolverSolver.php
│   └── CapMonsterSolver.php
├── Interpreter/
│   ├── JavaScriptInterpreterInterface.php
│   ├── InterpreterFactory.php
│   ├── NodeJsInterpreter.php
│   └── V8JsInterpreter.php
├── Exception/                    # 12 exception classes
│   ├── CloudflareException.php
│   ├── CloudflareLoopProtectionException.php
│   ├── CloudflareCode1020Exception.php
│   └── ...
└── Data/
    └── browsers.json             # UA, headers, and cipher suite database

Challenge Detection Priority

Turnstile — cf-turnstile div or Turnstile script
V3 — orchestrate/jsch/v3 or window._cf_chl_ctx
V2 CAPTCHA — orchestrate/(captcha|managed)/v1
V2 JS — orchestrate/jsch/v1
V1 — /cdn-cgi/images/trace/jsch/ + challenge form

Exception Hierarchy

CloudflareException
├── CloudflareLoopProtectionException
├── CloudflareCode1020Exception
├── CloudflareIUAMException
├── CloudflareChallengeException
├── CloudflareSolveException
├── CloudflareCaptchaException
├── CloudflareTurnstileException
└── CloudflareV3Exception

CaptchaException
├── CaptchaServiceException
└── CaptchaApiException

Testing

composer test

Static analysis:

composer phpstan

License

MIT

cloudscraper / cloudscraper-php

Maintainers

Package info

Statistics

Security