README

curl-impersonate-php

Stop getting blocked. Start impersonating real browsers.

PHP wrapper for curl-impersonate — execute HTTP requests that mimic real browser TLS fingerprints, bypassing Cloudflare, Akamai, Datadome, and other anti-bot systems.

Installation · Quick Start · Browser Presets · API · FAQ

Why This Exists

Regular curl has a distinct TLS fingerprint. Anti-bot systems detect it instantly.

curl-impersonate uses a patched libcurl that produces the exact same TLS ClientHello as Chrome, Firefox, or Safari. Your requests become indistinguishable from a real browser.

This library wraps it in a clean PHP API — no shell scripting required.

Regular curl    →  TLS fingerprint = "bot"     →  🚫 403 Blocked
curl-impersonate →  TLS fingerprint = "Chrome"  →  ✅ 200 OK

Installation

composer require kelvinzer0/curl-impersonate-php

Install curl-impersonate binary

# Linux x86_64 (v0.6.1)
curl -L https://github.com/lwthiker/curl-impersonate/releases/download/v0.6.1/curl-impersonate-v0.6.1.x86_64-linux-gnu.tar.gz | tar xz
export LD_LIBRARY_PATH="$PWD:$LD_LIBRARY_PATH"

# macOS (Homebrew)
brew install curl-impersonate

See curl-impersonate releases for all builds.

Quick Start

<?php
require 'vendor/autoload.php';

use CurlImpersonate\CurlImpersonate;

$curl = new CurlImpersonate();

// Option 1: Use a browser preset (auto-detects binary path)
$response = $curl
    ->setBrowser(CurlImpersonate::BROWSER_CHROME)
    ->setopt(CurlImpersonate::OPT_URL, 'https://example.com')
    ->setopt(CurlImpersonate::OPT_METHOD, 'GET')
    ->exec();

echo $response;

<?php
// Option 2: Point to a specific binary
$curl = new CurlImpersonate();
$response = $curl
    ->setopt(CurlImpersonate::OPT_URL, 'https://example.com')
    ->setopt(CurlImpersonate::OPT_ENGINE, '/path/to/curl_chrome116')
    ->exec();

Browser Presets

Preset	Constant	Mimics
Chrome 116	`BROWSER_CHROME`	Chrome 116 on Windows 10
Chrome 120	`BROWSER_CHROME_120`	Chrome 120 on Windows 10
Firefox 102	`BROWSER_FIREFOX`	Firefox 102 ESR on Linux
Firefox 117	`BROWSER_FIREFOX_117`	Firefox 117 on Linux
Safari 15.3	`BROWSER_SAFARI`	Safari 15.3 on macOS Monterey
Safari 17.0	`BROWSER_SAFARI_17`	Safari 17.0 on macOS Sonoma
Edge 99	`BROWSER_EDGE`	Edge 99 on Windows

$curl->setBrowser(CurlImpersonate::BROWSER_CHROME_120);

API

Options

$curl->setopt(int $option, mixed $value): self

Constant	Description	Example
`OPT_URL`	Target URL	`'https://api.example.com/data'`
`OPT_METHOD`	HTTP method	`'POST'`
`OPT_POSTFIELDS`	Request body (array → JSON)	`['key' => 'value']`
`OPT_HTTP_HEADERS`	Headers array	`['Authorization: Bearer xxx']`
`OPT_HEADER`	Include response headers	`true`
`OPT_ENGINE`	Path to curl-impersonate binary	`'/usr/local/bin/curl_chrome116'`
`OPT_PROXY`	Proxy (HTTP or SOCKS5)	`'socks5://127.0.0.1:1080'`
`OPT_TIMEOUT`	Request timeout (seconds)	`30`
`OPT_FOLLOW_LOCATION`	Follow redirects	`true`
`OPT_VERIFY_SSL`	Verify SSL certificates	`true`
`OPT_COOKIEFILE`	Read cookies from file	`'/tmp/cookies.txt'`
`OPT_COOKIEJAR`	Save cookies to file	`'/tmp/cookies.txt'`

Methods

// Execute and get response
$response = $curl->exec(): ?string

// Execute with streaming
$curl->execStream(): self
$chunk = $curl->readStream(4096): string|false
$curl->closeStream(): void

// Build command (for debugging)
$command = $curl->buildCommand(): string

// Reset for reuse
$curl->reset(): self

Examples

POST JSON with authentication

$curl = new CurlImpersonate();
$response = $curl
    ->setBrowser(CurlImpersonate::BROWSER_CHROME)
    ->setopt(CurlImpersonate::OPT_URL, 'https://api.example.com/users')
    ->setopt(CurlImpersonate::OPT_METHOD, 'POST')
    ->setopt(CurlImpersonate::OPT_POSTFIELDS, ['name' => 'Kelvin', 'role' => 'admin'])
    ->setopt(CurlImpersonate::OPT_HTTP_HEADERS, [
        'Authorization: Bearer YOUR_TOKEN',
        'Content-Type: application/json',
    ])
    ->exec();

SOCKS5 proxy

$curl = new CurlImpersonate();
$response = $curl
    ->setBrowser(CurlImpersonate::BROWSER_FIREFOX)
    ->setopt(CurlImpersonate::OPT_URL, 'https://check.torproject.org/api/ip')
    ->setopt(CurlImpersonate::OPT_PROXY, 'socks5h://127.0.0.1:9050')
    ->exec();

Stream large responses

$curl = new CurlImpersonate();
$curl
    ->setBrowser(CurlImpersonate::BROWSER_SAFARI)
    ->setopt(CurlImpersonate::OPT_URL, 'https://example.com/large-file')
    ->execStream();

while ($chunk = $curl->readStream(8192)) {
    echo $chunk; // process chunk by chunk
}

Scrape with cookies

$curl = new CurlImpersonate();

// Step 1: Login and save cookies
$curl
    ->setBrowser(CurlImpersonate::BROWSER_CHROME)
    ->setopt(CurlImpersonate::OPT_URL, 'https://example.com/login')
    ->setopt(CurlImpersonate::OPT_METHOD, 'POST')
    ->setopt(CurlImpersonate::OPT_POSTFIELDS, ['user' => 'admin', 'pass' => 'secret'])
    ->setopt(CurlImpersonate::OPT_COOKIEJAR, '/tmp/cookies.txt')
    ->exec();

// Step 2: Use saved cookies
$response = $curl
    ->reset()
    ->setBrowser(CurlImpersonate::BROWSER_CHROME)
    ->setopt(CurlImpersonate::OPT_URL, 'https://example.com/dashboard')
    ->setopt(CurlImpersonate::OPT_COOKIEFILE, '/tmp/cookies.txt')
    ->exec();

FAQ

Where do I get the curl-impersonate binary?

Download from releases or install via package manager:

# macOS
brew install curl-impersonate

# Arch Linux
yay -S curl-impersonate

# Docker
docker pull lwthiker/curl-impersonate:0.6.1

How do I use proxies?

Use OPT_PROXY with any proxy type curl supports:

// HTTP proxy
->setopt(CurlImpersonate::OPT_PROXY, 'http://user:pass@proxy.example.com:8080')

// SOCKS5 proxy
->setopt(CurlImpersonate::OPT_PROXY, 'socks5://127.0.0.1:1080')

// SOCKS5 with DNS resolution through proxy
->setopt(CurlImpersonate::OPT_PROXY, 'socks5h://127.0.0.1:1080')

I get "command not found" errors

Make sure curl-impersonate binaries are in your PATH or use the full path:

// Option 1: setBrowser with explicit path
->setBrowser(CurlImpersonate::BROWSER_CHROME, '/opt/curl-impersonate/bin')

// Option 2: direct engine path
->setopt(CurlImpersonate::OPT_ENGINE, '/opt/curl-impersonate/bin/curl_chrome116')

Does this work on shared hosting?

No. This library requires shell access to execute the curl-impersonate binary. It works on VPS, dedicated servers, Docker containers, and any environment where you can install system packages.

Comparison

Feature	Native curl	Guzzle	This library
TLS fingerprint	❌ Bot detection	❌ Bot detection	✅ Real browser
HTTP/2 fingerprint	❌	❌	✅ Real browser
Ja3 fingerprint	❌	❌	✅ Matched
PHP API	❌ Raw resource	✅ Clean	✅ Clean
Proxy support	✅	✅	✅
Streaming	✅	✅	✅

Who Uses This

Web scraping at scale without IP rotation
SEO monitoring tools
Price comparison services
API integration with anti-bot protected endpoints
Security research and testing

Contributing

See CONTRIBUTING.md.

License

⭐ Star this repo if it saved you from 403s

Report Bug · Request Feature

kelvinzer0 / curl-impersonate-php

Maintainers

Package info

Statistics

Security