README

A PHP wrapper for the tls-client library using PHP's FFI (Foreign Function Interface) extension.

Description

This library allows you to make HTTP requests with customizable TLS fingerprints from PHP, using the power of the tls-client library through FFI. It helps bypass TLS fingerprinting techniques used by some websites to detect and block non-browser traffic.

The library provides a convenient way to simulate various browser fingerprints, allowing you to make requests that appear to come from popular browsers like Chrome, Firefox, and Safari. This makes it particularly useful for web scraping and automated testing scenarios where you need to avoid detection.

This project is based on Sahil1337/node-tls-client, ported from Node.js to PHP. The primary improvement in this PHP version is the optimization of payload construction through dedicated builder classes.

Features

tls-client Features

• Make HTTP/1.1 and HTTP/2 requests with custom TLS fingerprints
• Support for various browser fingerprints (Chrome, Firefox, Safari, etc.)
• Custom JA3 fingerprinting
• Proxy support
• Cookie management
• Session persistence

PHP Wrapper Features

• Optimized payload construction using builder patterns
• Direct h2_fp string configuration support

Requirements

• PHP 7.4 or higher
• FFI extension enabled
• Internet connection (for automatic library download)

Installation

Via Composer (Recommended)

composer require xxx-bin/php-tls-client

Manual Installation

1. Make sure you have PHP 7.4+ with FFI extension enabled
2. Clone or download this repository
3. Run composer install to install dependencies

The required tls-client shared library will be automatically downloaded on first use.

Usage

<?php

require_once 'vendor/autoload.php';

use PHPTLSClient\Session;
use PHPTLSClient\Client;
use PHPTLSClient\ClientIdentifier;

// Initialize the TLS client
// The required shared library will be automatically downloaded if not found
Client::init();

// Or specify a custom library path
// Client::init('/path/to/tls-client-64.dll');

// Create a session with a specific browser fingerprint
$session = new Session([
    'tlsClientIdentifier' => ClientIdentifier::CHROME_124,
    'timeoutSeconds' => 30,
]);

try {
    // Make a GET request
    $response = $session->get('https://httpbin.org/get');
    
    echo "Status: " . $response->status() . "\n";
    echo "Body: " . $response->text() . "\n";
} finally {
    // Clean up
    $session->close();
    Client::destroy();
}

Advanced Usage

Custom TLS Configuration

For more advanced use cases, you can create custom TLS configurations using the builder pattern:

use PHPTLSClient\Payload\CustomTlsClient;
use PHPTLSClient\Payload\H2Config;
use PHPTLSClient\Payload\PriorityParam;

// Create H2 configuration from h2fp format
$h2Config = (new H2Config())
    ->fromH2FP('1:65536;4:131072;5:16384|12517377|3:0:0:201,5:0:0:101,7:0:0:1,9:0:7:1,11:0:3:1,13:0:0:241|m,p,a,s ')
    ->setHeaderPriority((new PriorityParam())
        ->setStreamDep(1)
        ->setExclusive(true)
        ->setWeight(254));

// Create custom TLS client configuration
$customTlsClient = (new CustomTlsClient())
    ->setJa3String("771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,10-16-5-11-27-13-0-18-65037-51-65281-17613-45-43-23-35,4588-29-23-24,0")
    ->setH2Config($h2Config)
    ->setSupportedSignatureAlgorithms([
        CustomTlsClient::SIGNATURE_ALGO_ECDSA_WITH_P256_AND_SHA256,
        CustomTlsClient::SIGNATURE_ALGO_PSS_WITH_SHA256,
        // ... more algorithms
    ])
    ->setSupportedVersions([
        CustomTlsClient::TLS_VERSION_GREASE,
        CustomTlsClient::TLS_VERSION_1_3,
        CustomTlsClient::TLS_VERSION_1_2,
    ])
    ->setKeyShareCurves([
        CustomTlsClient::KEY_SHARE_CURVE_GREASE,
        CustomTlsClient::KEY_SHARE_CURVE_X25519,
        // ... more curves
    ])
    ->setCertCompressionAlgos([CustomTlsClient::CERT_COMPRESSION_ALGO_BROTLI])
    ->setAlpnProtocols(["h2", "http/1.1"])
    ->setAlpsProtocols(["h2"])
    ->setHeaderOrder(["accept", "user-agent", "accept-encoding", "accept-language"]);

FFI Direct Usage

For advanced users who want to directly use FFI to call the tls-client library, check out the FFI_simple.php example. This shows how to directly interface with the C library using PHP's FFI extension. you can check it out in more detail。https://bogdanfinn.gitbook.io/open-source-oasis/shared-library/payload

Automatic Library Download

This library automatically downloads the required tls-client shared library for your platform on first use:

• Windows: tls-client-64.dll
• macOS: tls-client-arm64.dylib or tls-client-x86.dylib
• Linux: tls-client-x64.so or tls-client-arm64.so

The library is downloaded from the official tls-client releases page and saved to your system's temporary directory.

You can monitor the download progress as it happens.

Examples

Check out the examples directory for more detailed usage examples:

1. Simple request - Basic GET request
2. With headers - Request with custom headers
3. POST request - Sending data with POST
4. Using proxy - Making requests through a proxy
5. Custom JA3 - Using a custom TLS fingerprint
6. Custom JA3 with builder - Using a custom TLS fingerprint with the builder pattern
7. Multiple requests - Multiple requests in one session
8. With cookies - Working with cookies
9. FFI Simple - Direct FFI usage example

Session Options

The Session constructor accepts an array of options:

Request Options

Each request method (get, post, put, etc.) accepts an options array:

Commonly used options:

Response Methods

The response object has the following methods:

Client Identifiers

Available client identifiers (use the constants in ClientIdentifier class):

Chrome

• CHROME_103 to CHROME_112
• CHROME_116_PSK, CHROME_116_PSK_PQ
• CHROME_117, CHROME_120, CHROME_124
• CHROME_130_PSK
• CHROME_131, CHROME_131_PSK
• CHROME_133, CHROME_133_PSK
• CHROME_144, CHROME_144_PSK
• CHROME_146, CHROME_146_PSK

Brave

• BRAVE_146, BRAVE_146_PSK

Safari

• SAFARI_15_6_1, SAFARI_16_0
• SAFARI_IPAD_15_6
• SAFARI_IOS_15_5, SAFARI_IOS_15_6, SAFARI_IOS_16_0, SAFARI_IOS_17_0, SAFARI_IOS_18_0, SAFARI_IOS_18_5, SAFARI_IOS_26_0

Firefox

• FIREFOX_102 to FIREFOX_110
• FIREFOX_117, FIREFOX_120, FIREFOX_123
• FIREFOX_132, FIREFOX_133, FIREFOX_135
• FIREFOX_146_PSK
• FIREFOX_147, FIREFOX_147_PSK
• FIREFOX_148

Opera

• OPERA_89 to OPERA_91

Mobile Clients

• Zalando: ZALANDO_ANDROID_MOBILE, ZALANDO_IOS_MOBILE
• Nike: NIKE_IOS_MOBILE, NIKE_ANDROID_MOBILE
• MMS iOS: MMS_IOS, MMS_IOS_1, MMS_IOS_2, MMS_IOS_3
• Mesh: MESH_IOS, MESH_IOS_1, MESH_IOS_2, MESH_ANDROID, MESH_ANDROID_1, MESH_ANDROID_2
• Confirmed: CONFIRMED_IOS, CONFIRMED_ANDROID
• OkHttp Android: OKHTTP4_ANDROID_7 to OKHTTP4_ANDROID_13

Other

• CLOUDSCRAPER

Error Handling

The library throws exceptions for various error conditions:

• Exception when the shared library cannot be loaded or downloaded
• Request-specific exceptions during HTTP operations

Always wrap your code in try-catch blocks for proper error handling.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

This library is based on bogdanfinn's tls client in Go and the PHP wrapper implementation.