README

A Rust-based gRPC extension for PHP — drop-in replacement for the official ext-grpc.

Why?

The official C-based grpc extension has long-standing issues:

• ZTS/TSRM crashes — segfaults under FrankenPHP, Swoole, and other threaded SAPIs
• OpenSSL/BoringSSL conflicts — the bundled BoringSSL collides with PHP's OpenSSL, breaking ext-curl and other extensions

grpc-php-rs solves both by using a pure Rust stack: tonic for gRPC, rustls for TLS (no OpenSSL), and ext-php-rs for PHP bindings.

Install

Docker (recommended)

One line in your Dockerfile — no build tools needed:

FROM php:8.5-cli

COPY --from=ghcr.io/bsn4/grpc-php-rs:latest-php8.5 /usr/local/ /usr/local/

For ZTS (FrankenPHP, Swoole, etc.):

COPY --from=ghcr.io/bsn4/grpc-php-rs:latest-php8.5-zts /usr/local/ /usr/local/

For Alpine:

FROM php:8.5-alpine
COPY --from=ghcr.io/bsn4/grpc-php-rs:latest-php8.5-alpine /usr/local/ /usr/local/

Available tags: latest-php{8.2,8.3,8.4,8.5} for Debian, append -alpine for Alpine, append -zts for thread-safe (e.g. latest-php8.5-alpine-zts). Version-pinned tags like v0.2.1-php8.5-alpine are also available.

Via PIE

pie install bsn4/grpc

Requires PIE 1.4.0+ for pre-packaged binary support.

Manual download

Download the appropriate .so from the latest release, then:

# Copy to your PHP extensions directory
cp grpc.so $(php -r "echo ini_get('extension_dir');")

# Enable it
echo "extension=grpc" > $(php -r "echo PHP_CONFIG_FILE_SCAN_DIR;")/grpc.ini

Alpine note: When using the linux-musl binary outside of the Docker install image, you also need apk add --no-cache libgcc. The Docker install image bundles this for you.

Supported Platforms

Usage

grpc-php-rs is a drop-in replacement. Add to your php.ini:

extension=grpc

Then use the Grpc\ namespace as normal:

$channel = new \Grpc\Channel('localhost:50051', [
    'credentials' => \Grpc\ChannelCredentials::createInsecure(),
]);

All existing gRPC PHP code works unchanged — Grpc\Channel, Grpc\ChannelCredentials, Grpc\CallCredentials, Grpc\Timeval, and all call types (UnaryCall, ServerStreamingCall, ClientStreamingCall, BidiStreamingCall).

Building from Source

Requirements:

• Rust toolchain (stable; nightly required on Windows)
• PHP 8.2+ development headers (php-dev / php-devel)

cargo build --release
# Output: target/release/libgrpc_php_rs.so (Linux) or libgrpc_php_rs.dylib (macOS) or grpc_php_rs.dll (Windows)

Running Tests

./test.sh all       # Build Docker images + run smoke & compatibility tests
./test.sh zts       # ZTS stress test with FrankenPHP + concurrent requests
./test.sh smoke     # PHP smoke test only
./test.sh shell     # Drop into PHP CLI with extension loaded

See ./test.sh --help for all options.

License

MIT