README

PhpSocks

SOCKS5 proxy client, written in pure PHP with zero dependencies.

Features

• Supports SOCKS5 protocol
• Implements the CONNECT command
• Implements UDP ASSOCIATE command
• Supports username/password authentication (RFC 1929)

Requirements

• PHP 7.4 or higher
• Sockets extension enabled

Installation

Install via Composer:

composer require rovazh/phpsocks

Usage

Tunneling TCP connections through a SOCKS5 server (CONNECT)

Plain TCP connections

The following example demonstrates connecting to example.net on port 80 via a SOCKS5 proxy server:

$client = new \PhpSocks\Client([ 'host' => '127.0.0.1', // SOCKS5 server (IPv4, IPv6, or hostname) 'port' => 1080, // SOCKS5 server port ]); try { $stream = $client->connect('tcp://example.net:80'); $stream->write("GET / HTTP/1.0\r\n\r\n"); echo $stream->read(1024); $stream->close(); } catch (\PhpSocks\Exception\PhpSocksException $e) { // Handle exception }

Secure TLS connections

The following example demonstrates establishing a secure TLS connection to example.net on port 443 via a SOCKS5 proxy server:

$client = new \PhpSocks\Client([ 'host' => '127.0.0.1', 'port' => 1080, ]); try { $stream = $client->connect('tls://example.net:443'); $stream->write("GET / HTTP/1.0\r\n\r\n"); echo $stream->read(1024); $stream->close(); } catch (\PhpSocks\Exception\PhpSocksException $e) { // Handle exception }

The connect method accepts an associative array of SSL context options that can be used to configure TLS settings when connecting to a destination host.

$client = new \PhpSocks\Client([ 'host' => '127.0.0.1', 'port' => 1080, ]); try { $stream = $client->connect('tls://example.net:443', [ 'tls' => [ 'verify_peer' => false, ] ]); $stream->write("GET / HTTP/1.0\r\n\r\n"); echo $stream->read(1024); $stream->close(); } catch (\PhpSocks\Exception\PhpSocksException $e) { // Handle exception }

Note: SSL context options have no effect when using a plain TCP connection (tcp://).

Authentication

PhpSocks supports username/password authentication for SOCKS5 servers as defined in RFC 1929.

$client = new \PhpSocks\Client([ 'host' => '127.0.0.1', 'port' => 1080, 'auth' => [ 'username' => 'proxy_user', 'password' => 'proxy_pass', ] ]);

Timeout Settings

By default, the library relies on the system's default_socket_timeout when connecting to a SOCKS5 server. To set a custom timeout at runtime, use the connect_timeout option:

$client = new \PhpSocks\Client([ 'host' => '127.0.0.1', 'port' => 1080, 'connect_timeout' => 5.0, // 5 seconds ]);

Additionally, you can set a timeout for sending and receiving data. By default, this is determined by the operating system. To explicitly define it, use the timeout option:

$client = new \PhpSocks\Client([ 'host' => '127.0.0.1', 'port' => 1080, 'connect_timeout' => 5.0, // 5 seconds 'timeout' => 3, // 3 seconds ]);

Relaying UDP Datagrams through a SOCKS5 Server (UDP ASSOCIATE)

The following example establishes a SOCKS5 UDP association to enable relaying UDP datagrams to example.net on port 5023 via a SOCKS5 proxy server:

$client = new \PhpSocks\Client([ 'host' => '127.0.0.1', // SOCKS5 server (IPv4, IPv6, or hostname) 'port' => 1080, // SOCKS5 server port ]); try { $stream = $client->associate('udp://example.net:5023'); $stream->write("Hello"); echo $stream->read(1024); $stream->close(); } catch (\PhpSocks\Exception\PhpSocksException $e) { // Handle exception }

License

PhpSocks is distributed under the terms of the MIT License. See LICENSE file for details.