Download the PHP package 18230/php-tuic-client without Composer

php-tuic-client

中文文档

php-tuic-client is a pure PHP TUIC v5 client focused on one job: start a local socks5://127.0.0.1:1080 style proxy and relay it through a TUIC node.

The QUIC transport is provided by cloudflare/quiche through PHP FFI. The local accept loop, node parsing, CLI flow, and runtime control stay in PHP.

Scope

• TUIC v5 authentication
• local SOCKS5 server
• Clash-style YAML / JSON node parsing
• Windows, Linux, and macOS project support
• cross-platform startup scripts
• doctor and run CLI workflow
• compatibility request helpers for framework projects, built on top of the same local SOCKS5 runtime

Not in scope right now:

• UDP relay
• HTTP proxy runtime
• multi-node scheduling

Requirements

• PHP 8.2.4+
• ext-ffi
• ext-json
• ext-openssl
• ext-sockets
• a loadable libquiche shared library

Install

Official release tags vendor prebuilt libquiche binaries for:

• windows-x64
• linux-x64
• macos-x64

That means a normal composer require from a tagged release can use the bundled shared library directly. If you install from dev-main or run on another architecture, build your own library and point QUICHE_LIB or --quiche-lib at it.

Build libquiche

Official releases already include prebuilt x64 libraries. Build manually only if you are developing locally, using dev-main, or targeting another architecture.

You need a shared quiche build with the ffi feature enabled.

Windows:

Linux / macOS:

If your library lives outside the default search locations, point QUICHE_LIB or --quiche-lib to the absolute path.

Quick Start

Validate runtime prerequisites:

The doctor command prints the detected native triplet and the library search order. On official release installs it should resolve the bundled file under resources/native/<platform>-<arch>/.

Start with inline YAML:

Or start from a config file:

Then point your tools at:

For command-line tools, prefer socks5h:// so DNS resolution also goes through the proxy:

Examples:

Node Fields

Required TUIC node fields:

• name: local display name
• type: must be tuic
• server: remote TUIC server hostname or IP
• port: remote TUIC port
• uuid: TUIC user UUID
• password: TUIC password / token
• alpn: usually [h3]
• sni: TLS server name

Supported optional fields:

• skip-cert-verify: defaults to false
• disable-sni: defaults to false
• reduce-rtt: defaults to false
• udp-relay-mode: parsed but UDP relay is not implemented yet
• congestion-controller: typically bbr

Minimal example:

CLI

Main options:

• --node
• --config
• --node-name
• --listen
• --allow-ip
• --max-connections
• --connect-timeout
• --idle-timeout
• --handshake-timeout
• --status-file
• --status-interval
• --log-file
• --pid-file
• --quiche-lib
• --dry-run

Production-style example:

Node Example

Runtime Outputs

When you run the proxy in production, these files are the most useful:

• log-file: human-readable runtime log
• status-file: JSON snapshot of listener, node, and counters
• pid-file: current process ID

The status-file includes counters such as:

• accepted_connections_total
• closed_connections_total
• handshake_timeouts_total
• tuic_auth_success_total
• tuic_auth_failure_total

Production Notes

• Keep the SOCKS5 listener on loopback unless you truly need LAN access.
• Run doctor against the exact PHP binary that will host the long-running process.
• Official release tags already ship bundled x64 native libraries inside the Composer package.
• Production flags stay intentionally small and explicit: allow-ip, max-connections, connect-timeout, idle-timeout, handshake-timeout, status-file, log-file, and pid-file.
• If you deploy on another architecture, ship your own libquiche with the same artifact and either place it under the matching triplet directory or set QUICHE_LIB.
• Prefer Linux for long-running production workloads.

Troubleshooting

• doctor fails before startup: Run php bin/tuic-client doctor ... with the exact PHP binary you will use in production.
• ext-ffi is disabled: Enable FFI in php.ini, then rerun doctor.
• libquiche cannot be found: Use the tagged release package or point QUICHE_LIB / --quiche-lib at the absolute library path.
• The process starts but local requests fail: Check log-file and status-file first. If tuic_auth_failure_total is non-zero, verify node credentials, SNI, and TLS settings.
• Windows / Linux / macOS mismatch: Make sure the packaged native library matches the current platform and architecture.

Framework Helpers

The package still ships TuicRequestClient and framework service providers for Laravel / ThinkPHP. These helpers are convenience layers built on top of the same local SOCKS5 runtime plus cURL. They are optional and not required if you only want the protocol-level local proxy.

More detail:

• English production guide
• 中文生产部署说明

Testing

The release pipeline also runs a real-node end-to-end probe on ubuntu-22.04, windows-latest, and macos-15-intel using the packaged libquiche binaries and a local socks5://127.0.0.1:11084 listener.