README

PHP curl_cffi

PHP bindings for curl-impersonate via FFI, with browser fingerprint impersonation support.

Overview

PHP curl_cffi is a comprehensive port of the popular Python curl_cffi library, providing low-level and high-level interfaces to libcurl-impersonate using PHP's FFI (Foreign Function Interface) extension. This library allows PHP applications to impersonate TLS/JA3 and HTTP/2 client fingerprints of major browsers (Chrome, Firefox, Safari), making it highly effective for web scraping and bypassing anti-bot solutions like Cloudflare, Akamai, and others.

Features

• Browser Impersonation: Spoof JA3 TLS and HTTP/2 browser fingerprints out of the box (e.g. Chrome 110, Firefox 100, etc.).
• High-Level Requests API: Simple static shortcuts like Requests::get(), Requests::post(), matching Python's requests interface.
• Stateful Sessions: Maintain cookies, headers, proxies, and connection reuse across multiple HTTP requests.
• Concurrent Requests: Perform concurrent non-blocking HTTP requests using the FFI-powered MultiSession wrapper.
• WebSockets Support: Connect, send, and receive text/binary frames dynamically using native libcurl WebSocket APIs.
• Autoloading & Auto-Configured Exception Map: Automatically map curl error codes to specialized exceptions like DNSError or ProxyError.

Prerequisites

• PHP 8.1 or higher.
• PHP FFI extension enabled (extension=ffi in php.ini).
• For web servers (FPM/Apache), ensure ffi.enable=on is configured in php.ini.

Installation

1. Install the PHP Library

Install the package via Composer:

composer require farhaanaliii/curl-cffi

2. Install the Native Library (libcurl-impersonate)

This library loads libcurl-impersonate dynamically using PHP FFI. You must install the compiled binary (.dll, .so, or .dylib) on your system:

Option A: Set Environment Variable (Recommended)

You can download the precompiled library and point to it directly in your application code or environment configuration:

// Define this before making any CurlCffi calls (e.g., in your bootstrap file)
putenv("CURL_CFFI_LIB_PATH=/path/to/libcurl-impersonate.so");

Option B: Install to System PATH

Download the precompiled binary matching your architecture from the curl-impersonate Releases:

• Linux (Debian/Ubuntu):

  1. Download the libcurl-impersonate-v*.aarch64-linux-gnu.tar.gz (ARM64) or libcurl-impersonate-v*.x86_64-linux-gnu.tar.gz (x86_64).
  2. Extract the file and copy libcurl-impersonate.so (and any related symlinks) to /usr/local/lib/.
  3. Run sudo ldconfig to update the system dynamic linker cache.

• macOS:

  1. Download libcurl-impersonate-v*.macos.tar.gz matching your CPU (ARM64 / Apple Silicon or Intel).
  2. Copy libcurl-impersonate.dylib to /usr/local/lib/.

• Windows:

  1. Download libcurl-impersonate-v*.x86_64-win32.tar.gz.
  2. Extract and copy libcurl-impersonate.dll.
  3. Place it in your system PATH (e.g. C:\Windows\System32), or directly in your PHP installation folder (the same directory containing php.exe).

Usage

Simple GET Request

<?php

require_once 'vendor/autoload.php';

use CurlCffi\Requests;

$response = Requests::get("https://httpbin.org/headers", [
    'impersonate' => 'chrome110'
]);

echo "Status: " . $response->statusCode . "\n";
echo "Body:\n" . $response->getText() . "\n";

Session Management

<?php

require_once 'vendor/autoload.php';

use CurlCffi\Session;

$session = new Session();

$response1 = $session->post("https://httpbin.org/post", [
    'json' => ['username' => 'testuser'],
    'impersonate' => 'chrome110'
]);

$response2 = $session->get("https://httpbin.org/cookies", [
    'impersonate' => 'chrome110'
]);

echo $response2->getText();

Concurrent Requests via MultiSession

<?php

require_once 'vendor/autoload.php';

use CurlCffi\MultiSession;

$multi = new MultiSession();

$id1 = $multi->add('GET', 'https://httpbin.org/headers', [
    'impersonate' => 'chrome110'
]);

$id2 = $multi->add('GET', 'https://httpbin.org/html', [
    'impersonate' => 'chrome110'
]);

$results = $multi->perform();

foreach ($results as $id => $res) {
    if ($res instanceof \Exception) {
        echo "Request {$id} failed: " . $res->getMessage() . "\n";
    } else {
        echo "Request {$id} status: " . $res->statusCode . "\n";
    }
}

$multi->close();

WebSockets

<?php

require_once 'vendor/autoload.php';

use CurlCffi\WebSocket;

$ws = new WebSocket();
$ws->connect("wss://ws.postman-echo.com/raw");

$ws->sendStr("Hello WebSocket!");
$reply = $ws->recvStr(5.0);

echo "Server said: " . $reply . "\n";

$ws->close();

Authors & Credits

• Author: Farhaan Ali (GitHub: @farhaanaliii)
• Original Projects:
  • Python curl_cffi wrapper: lexiforest/curl_cffi
  • Precompiled curl-impersonate libraries: lexiforest/curl-impersonate

License

This project is open-source and licensed under the MIT License. See LICENSE for details.