PHPackages                             thesis/grpc-server - 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. [API Development](/categories/api)
4. /
5. thesis/grpc-server

ActiveLibrary[API Development](/categories/api)

thesis/grpc-server
==================

Async gRPC server for PHP with HTTP/2 transport, unary and streaming RPC handlers, interceptors, and graceful shutdown.

0.1.6(1mo ago)0152MITPHPPHP ^8.4CI failing

Since Apr 10Pushed 1mo agoCompare

[ Source](https://github.com/thesis-php/grpc-server)[ Packagist](https://packagist.org/packages/thesis/grpc-server)[ Fund](https://www.tinkoff.ru/cf/5MqZQas2dk7)[ RSS](/packages/thesis-grpc-server/feed)WikiDiscussions 0.1.x Synced 1w ago

READMEChangelog (4)Dependencies (6)Versions (6)Used By (2)

thesis/grpc-server
==================

[](#thesisgrpc-server)

> Read-only subtree split from `https://github.com/thesis-php/grpc`.
>
> Do not open issues/PRs here. Use the monorepo:
>
> -
> -

Async gRPC server for PHP with HTTP/2 transport, unary and streaming RPC handlers, interceptors, and graceful shutdown.

Contents
--------

[](#contents)

- [Installation](#installation)
- [Requirements](#requirements)
- [Implementing a service](#implementing-a-service)
- [Starting the server](#starting-the-server)
- [TLS and mTLS](#tls-and-mtls)
- [Compression](#compression)
- [Interceptors](#interceptors)
- [RPC types](#rpc-types)
- [Stream decorators](#stream-decorators)
- [Graceful shutdown](#graceful-shutdown)

Installation
------------

[](#installation)

```
composer require thesis/grpc-server
```

Requirements
------------

[](#requirements)

To generate gRPC server interfaces and registries from `.proto`, use:

-

Implementing a service
----------------------

[](#implementing-a-service)

```
use Amp\Cancellation;
use Auth\Api\V1\AuthenticateRequest;
use Auth\Api\V1\AuthenticateResponse;
use Auth\Api\V1\AuthenticationServiceServer;
use Thesis\Grpc\Metadata;

final readonly class AuthenticationServer implements AuthenticationServiceServer
{
    public function authenticate(AuthenticateRequest $request, Metadata $md, Cancellation $cancellation): AuthenticateResponse
    {
        return new AuthenticateResponse('supertoken');
    }
}
```

Starting the server
-------------------

[](#starting-the-server)

```
use Auth\Api\V1\AuthenticationServiceServerRegistry;
use Thesis\Grpc\Server;
use function Amp\trapSignal;

$server = new Server\Builder()
    ->withServices(new AuthenticationServiceServerRegistry(new AuthenticationServer()))
    ->build();

$server->start();
trapSignal([\SIGINT, \SIGTERM]);
$server->stop();
```

Default bind address: `0.0.0.0:50051`.

Use `withAddresses()` to override bind addresses:

```
$server = new Server\Builder()
    ->withAddresses('0.0.0.0:8080')
    ->build();
```

TLS and mTLS
------------

[](#tls-and-mtls)

```
use Amp\Socket\Certificate;
use Thesis\Grpc\Server;

$server = new Server\Builder()
    ->withTransportCredentials(
        new Server\TransportCredentials()
            ->withDefaultCertificate(new Certificate('/certs/server.crt', '/certs/server.key'))
            ->withCaCert('/certs/ca.crt')
            ->withVerifyPeer(), // optional (mTLS)
    )
    ->build();
```

Practical recommendations:

- Ensure server certificate SAN (`DNS` / `IP`) matches what clients pass via `withPeerName()`.
- For mTLS, use certificates with correct `extendedKeyUsage` (`serverAuth` for server, `clientAuth` for client).
- Prefer certificates signed by a trusted CA and modern algorithms (for example, SHA-256).

Compression
-----------

[](#compression)

Register one or more compressors on the server:

```
use Thesis\Grpc\Compression\GzipCompressor;

$server = new Server\Builder()
    ->withCompressors(new GzipCompressor())
    ->build();
```

Interceptors
------------

[](#interceptors)

Interceptors let you apply cross-cutting server logic like auth, audit, tracing, and request validation around every RPC.

```
use Amp\Cancellation;
use Thesis\Grpc\Metadata;
use Thesis\Grpc\Server;
use Thesis\Grpc\Server\StreamInfo;
use Thesis\Grpc\ServerStream;

final readonly class ServerAuthInterceptor implements Server\Interceptor
{
    public function intercept(ServerStream $stream, StreamInfo $info, Metadata $md, Cancellation $cancellation, callable $next): void
    {
        $next($stream, $info, $md, $cancellation);
    }
}
```

RPC types
---------

[](#rpc-types)

Generated server interfaces expose all four gRPC RPC models directly:

- unary request/response
- client streaming
- server streaming
- bidirectional streaming

Unary example:

```
use Amp\Cancellation;
use Echos\Api\V1\EchoRequest;
use Echos\Api\V1\EchoResponse;
use Echos\Api\V1\EchoServiceServer;
use Thesis\Grpc\Metadata;

final readonly class EchoServer implements EchoServiceServer
{
    public function echo(EchoRequest $request, Metadata $md, Cancellation $cancellation): EchoResponse
    {
        return new EchoResponse($request->sentence);
    }
}
```

Client streaming example:

```
use Amp\Cancellation;
use File\Api\V1\Chunk;
use File\Api\V1\FileInfo;
use File\Api\V1\FileServiceServer;
use Thesis\Grpc\Metadata;
use Thesis\Grpc\Server;

final readonly class FileServer implements FileServiceServer
{
    public function upload(Server\ClientStreamChannel $stream, Metadata $md, Cancellation $cancellation): FileInfo
    {
        $size = 0;

        /** @var Chunk $chunk */
        foreach ($stream as $chunk) {
            $size += \strlen($chunk->content);
        }

        return new FileInfo($size);
    }
}
```

Server streaming example:

```
use Amp\Cancellation;
use Topic\Api\V1\Event;
use Topic\Api\V1\SubscribeRequest;
use Topic\Api\V1\TopicServiceServer;
use Thesis\Grpc\Metadata;

final readonly class TopicServer implements TopicServiceServer
{
    public function subscribe(SubscribeRequest $request, Metadata $md, Cancellation $cancellation): iterable
    {
        yield new Event('event-1', '{"id":1}');
        yield new Event('event-2', '{"id":2}');
    }
}
```

Bidirectional streaming example:

```
use Amp\Cancellation;
use Chat\Api\V1\Message;
use Chat\Api\V1\MessengerServiceServer;
use Thesis\Grpc\Metadata;
use Thesis\Grpc\Server;

final readonly class MessengerServer implements MessengerServiceServer
{
    public function chat(Server\BidirectionalStreamChannel $stream, Metadata $md, Cancellation $cancellation): void
    {
        foreach ($stream as $message) {
            $stream->send(new Message("echo: {$message->text}"));
        }

        $stream->close();
    }
}
```

Stream decorators
-----------------

[](#stream-decorators)

If you need per-message interception (not just per-RPC), decorate server streams.

```
use Psr\Log\LoggerInterface;
use Thesis\Grpc\Server;
use Thesis\Grpc\ServerStream;

/**
 * @template-covariant In of object
 * @template Out of object
 * @template-extends Server\DecoratedStream
 */
final class LoggingServerStream extends Server\DecoratedStream
{
    public function __construct(
        ServerStream $stream,
        private readonly LoggerInterface $logger,
    ) {
        parent::__construct($stream);
    }

    public function send(object $message): void
    {
        $this->logger->info('sent {type}', ['type' => $message::class]);
        parent::send($message);
    }

    public function receive(): object
    {
        $message = parent::receive();
        $this->logger->info('recv {type}', ['type' => $message::class]);

        return $message;
    }
}
```

Graceful shutdown
-----------------

[](#graceful-shutdown)

`Server::stop()` stops accepting new requests and waits for active handlers. You can pass `TimeoutCancellation` to bound wait time. Handlers receive `Cancellation`; they should respect it so shutdown can finish promptly.

```
use Amp\TimeoutCancellation;

$server->stop(new TimeoutCancellation(30));
```

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance93

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

6

Last Release

36d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2552865?v=4)[Valentin Udaltsov](/maintainers/vudaltsov)[@vudaltsov](https://github.com/vudaltsov)

---

Top Contributors

[![kafkiansky](https://avatars.githubusercontent.com/u/37590388?v=4)](https://github.com/kafkiansky "kafkiansky (3 commits)")

### Embed Badge

![Health badge](/badges/thesis-grpc-server/health.svg)

```
[![Health](https://phpackages.com/badges/thesis-grpc-server/health.svg)](https://phpackages.com/packages/thesis-grpc-server)
```

###  Alternatives

[danog/madelineproto

Async PHP client API for the telegram MTProto protocol.

3.4k885.1k21](/packages/danog-madelineproto)[amphp/http-server

A non-blocking HTTP application server for PHP based on Amp.

1.3k5.9M101](/packages/amphp-http-server)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[algolia/algoliasearch-client-php

API powering the features of Algolia.

69534.4M144](/packages/algolia-algoliasearch-client-php)[avalara/avataxclient

Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API.

528.3M7](/packages/avalara-avataxclient)[keboola/storage-api-client

Keboola Storage API PHP Client

10397.4k31](/packages/keboola-storage-api-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)