PHPackages                             gaoqi/php-tuic-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. gaoqi/php-tuic-client

ActiveLibrary[HTTP & Networking](/categories/http)

gaoqi/php-tuic-client
=====================

Pure PHP TUIC client with a local SOCKS5 proxy runtime backed by cloudflare/quiche FFI.

v0.2.4(2mo ago)10MITPHPPHP ^8.2.4CI passing

Since Mar 30Pushed 2mo agoCompare

[ Source](https://github.com/18230/php-tuic-client)[ Packagist](https://packagist.org/packages/gaoqi/php-tuic-client)[ Docs](https://github.com/18230/php-tuic-client)[ RSS](/packages/gaoqi-php-tuic-client/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (3)Dependencies (8)Versions (7)Used By (0)

php-tuic-client
===============

[](#php-tuic-client)

[![CI](https://camo.githubusercontent.com/848c4865c14f0bf8a9de4cc6acc23dd59223c52839796a050b2909d51fe12d78/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f31383233302f7068702d747569632d636c69656e742f63692e796d6c3f6272616e63683d6d61696e266c6162656c3d6369)](https://github.com/18230/php-tuic-client/actions/workflows/ci.yml)[![Native](https://camo.githubusercontent.com/be178de389a7b29b64ab9d5dc6a89572c576a314b53328962d2f5997a3e78c64/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f31383233302f7068702d747569632d636c69656e742f6e61746976652d6275696c642e796d6c3f6272616e63683d6d61696e266c6162656c3d6e6174697665)](https://github.com/18230/php-tuic-client/actions/workflows/native-build.yml)[![Release](https://camo.githubusercontent.com/6557f3c975c4f1837a5cc5be539b125bf7ee68c40ac3f12160965f69238f9b00/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f7461672f31383233302f7068702d747569632d636c69656e743f6c6162656c3d72656c65617365)](https://github.com/18230/php-tuic-client/tags)[![Packagist Version](https://camo.githubusercontent.com/cbe36780cadbff3bba0c5646716e4455b1cb72ed25306dcc4a0da65f8b87796f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f31383233302f7068702d747569632d636c69656e743f6c6162656c3d7061636b6167697374)](https://packagist.org/packages/18230/php-tuic-client)[![License](https://camo.githubusercontent.com/64e04e2cf16b0a0346882fc6c888ad761d68dd58ed044866e0abb2b9cc7c8565/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f31383233302f7068702d747569632d636c69656e74)](LICENSE)[![PHP](https://camo.githubusercontent.com/0c7c5db561e9b46e883a82a3725af2e635e08c8f63a50fae861dbfdbc0d775d2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322e342532422d373737626234)](https://www.php.net/)

[中文文档](README.zh-CN.md)

`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
-----

[](#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
------------

[](#requirements)

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

Install
-------

[](#install)

```
composer require 18230/php-tuic-client
```

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
---------------

[](#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:

```
.\scripts\build-quiche.ps1
```

Linux / macOS:

```
./scripts/build-quiche.sh
```

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

Quick Start
-----------

[](#quick-start)

Validate runtime prerequisites:

```
php bin/tuic-client doctor --config=examples/node.example.yaml
```

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/-/`.

Start with inline YAML:

```
php bin/tuic-client \
  --node="{ name: 'SG 01', type: tuic, server: your-tuic-server.example.com, port: 443, uuid: 11111111-1111-1111-1111-111111111111, password: your-password, alpn: [h3], disable-sni: false, reduce-rtt: false, udp-relay-mode: native, congestion-controller: bbr, skip-cert-verify: false, sni: your-tuic-server.example.com }" \
  --listen=127.0.0.1:1080
```

Or start from a config file:

```
php bin/tuic-client --config=examples/node.example.yaml --listen=127.0.0.1:1080
```

Then point your tools at:

```
socks5://127.0.0.1:1080

```

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

```
curl --proxy socks5h://127.0.0.1:1080 https://api.ipify.org?format=json
```

Examples:

```