Download the PHP package 18230/shadowsocks-local without Composer

php-shadowsocks-client

中文文档

php-shadowsocks-client is a pure-PHP Shadowsocks client package. It exposes a local SOCKS5 endpoint through the bundled ss-local runtime and relays TCP traffic to a remote Shadowsocks server by using Workerman as the long-running runtime.

Features

• PHP 8.2+
• Windows, Linux, and macOS
• Composer package with a CLI entrypoint
• Pure PHP SOCKS5 frontend and Shadowsocks TCP relay
• aes-256-gcm
• YAML, JSON, and ss:// node parsing
• Reusable ProxyService helpers for application code
• Laravel and ThinkPHP integration entry points
• Cross-platform startup scripts for development and production
• GitHub Actions Ubuntu CI workflow for Linux validation

Current Scope

Implemented:

• SOCKS5 CONNECT
• Shadowsocks TCP relay
• CLI startup command
• TLS helper objects for PHP curl and Guzzle
• Structured logging and basic runtime guards

Not implemented yet:

• UDP relay
• SIP003 plugins
• AEAD-2022 methods
• Additional ciphers beyond aes-256-gcm

Installation

Install from Packagist:

For local development in this repository:

Quick Start

Start with explicit options:

Start with inline YAML:

Start with a config file:

Validate the runtime and configuration before you start:

Check available options:

Application Usage

PHP curl

Guzzle

CLI curl

Configuration

The CLI accepts configuration from:

• --server, --port, --cipher, --password
• --node with inline YAML, JSON, or ss://
• --config with YAML or JSON files

Recommended config file structure:

Useful runtime options:

• --listen=127.0.0.1:1080
• --worker-count=1
• --max-connections=1024
• --allow-ip=127.0.0.1,::1
• --connect-timeout=10
• --connect-retries=1
• --retry-delay-ms=250
• --idle-timeout=900
• --max-send-buffer=4194304
• --status-file=/path/to/ss-local.status.json
• --status-interval=10
• --log-file=/path/to/ss-local.log
• --pid-file=/path/to/ss-local.pid
• --daemon on non-Windows platforms
• --verbose-log

What these production-oriented runtime options do:

• worker_count: number of Workerman worker processes on Unix-like platforms. Windows always runs a single worker.
• max_connections: per-worker cap for active client sessions. New clients are rejected after the cap is reached.
• allow_ips: optional client IP allowlist. Supports exact IPs and CIDR ranges.
• connect_retries and retry_delay_ms: simple retry policy for the initial upstream Shadowsocks connect phase.
• status_file: periodic JSON status snapshot for ops checks or sidecar monitoring.
• status_interval: write interval for the status snapshot in seconds.

See node.example.yaml for a file-based example.

TLS / CA Configuration

The proxy itself does not need a CA file. Your PHP application needs one when it accesses https:// endpoints and wants certificate verification to succeed.

If curl.cainfo and openssl.cafile are not configured, PHP curl can fail even when the proxy works correctly.

Template:

• resources/php/cacert.ini.example

Framework Integration

• English framework guide
• 中文框架接入说明

Production Deployment

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

Recommended minimum production posture:

• Keep the local listen address on loopback unless you explicitly need LAN access
• Use --allow-ip if you bind beyond loopback
• Run php bin/ss-local doctor ... before deploying
• Keep worker_count=1 unless you have validated your workload on Unix
• Enable status_file and log_file so operational failures are visible

Release Notes

• English release checklist
• English Packagist publishing guide
• 中文发布检查清单
• 中文 Packagist 发布说明
• Changelog

Examples

• Node config example
• Environment example
• PHP curl example
• Guzzle example

Testing

Notes for Publishing

• The Packagist package name for this repository is 18230/php-shadowsocks-client.
• The first tag intended for the renamed package is v0.2.0.
• The previous package name 18230/shadowsocks-local should be treated as a legacy package name.
• Run composer validate --strict and composer test before tagging a release.
• To keep Packagist in sync after every push, add the PACKAGIST_API_TOKEN repository secret and optionally the PACKAGIST_USERNAME repository variable.
• To remove the "not auto-updated" warning on Packagist, run the native GitHub hook setup script once: scripts/setup-packagist-github-hook.ps1 or scripts/setup-packagist-github-hook.sh.