folk-plugin-grpc

gRPC plugin for Folk — accepts gRPC calls via tonic/HTTP2 and dispatches to PHP workers. No Rust protobuf codegen required — all protobuf handling happens in PHP.

Configuration

Add to folk.build.toml:

[[plugin]]
crate_name = "folk-plugin-grpc"
version = "0.1"
config_key = "grpc"

Configure in folk.toml:

[grpc]
listen = "0.0.0.0:50051"

Settings

Full example:

[grpc]
listen = "0.0.0.0:50051"

Currently, clients must provide the .proto file for service discovery:

grpcurl -plaintext -proto proto/greeter.proto localhost:50051 list
grpcurl -plaintext -proto proto/greeter.proto localhost:50051 describe greeter.Greeter

How it works

gRPC client ──HTTP/2──> folk-plugin-grpc (Rust)
                            │
                            ├── extracts service, method, payload, metadata from request
                            ├── encodes as MessagePack {service, method, payload, metadata}
                            └── dispatches to PHP worker via grpc.call RPC
                                    │
                                    ▼
                              PHP handler
                                    │
                                    ├── decodes protobuf request (google/protobuf PHP)
                                    ├── executes business logic
                                    ├── encodes protobuf response
                                    └── returns raw bytes
                                    │
                                    ▼
                            folk-plugin-grpc
                                    │
                                    └── wraps in gRPC frame, sends HTTP/2 response

The Rust plugin handles HTTP/2, gRPC framing, and metadata extraction. PHP handles protobuf serialization and business logic.

Metadata

gRPC metadata (the equivalent of HTTP headers) is extracted from the request and passed to PHP handlers via Context. Standard HTTP/2 and gRPC internal headers are filtered out — everything else is available:

$ctx->getValue('authorization');  // "Bearer eyJ..."
$ctx->getValue('x-request-id');   // "abc-123"
$ctx->getMetadata();              // all metadata as array

Usage with folk-sdk (plain PHP)

1. Define your proto

syntax = "proto3";
package greeter;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest { string name = 1; }
message HelloReply { string message = 1; }

2. Generate PHP classes

protoc --php_out=. proto/greeter.proto

This generates message classes (HelloRequest, HelloReply) but not service interfaces. You write the handler manually.

3. Write the handler (raw bytes mode)

<?php

use Folk\Sdk\Grpc\GrpcModeHandler;
use Folk\Sdk\Grpc\Context;

class GreeterHandler implements GrpcModeHandler
{
    public function call(string $service, string $method, string $payload, Context $context): string
    {
        return match ($method) {
            'SayHello' => $this->sayHello($payload, $context),
            default => throw new \RuntimeException("Unknown method: {$method}"),
        };
    }

    private function sayHello(string $payload, Context $context): string
    {
        $request = new \Greeter\HelloRequest();
        $request->mergeFromString($payload);

        $token = $context->getValue('authorization'); // metadata access

        $reply = new \Greeter\HelloReply();
        $reply->setMessage("Hello, {$request->getName()}!");

        return $reply->serializeToString();
    }
}

4. Register

$loop = new \Folk\Sdk\Worker\WorkerLoop();
$loop->registerGrpcHandler(new GreeterHandler());
$loop->run();

Usage with Laravel (folk-laravel)

Laravel integration uses typed handlers with auto-detection of protobuf parameters.

1. Define your proto and generate PHP classes

protoc --php_out=app/Proto proto/greeter.proto

2. Create a service interface

<?php
// app/Proto/Greeter/GreeterInterface.php

namespace App\Proto\Greeter;

use Folk\Sdk\Grpc\ServiceInterface;

interface GreeterInterface extends ServiceInterface
{
    public const NAME = "greeter.Greeter";

    public function SayHello(HelloRequest $in): HelloReply;
    public function SayGoodbye(HelloRequest $in): HelloReply;
}

The NAME constant must match the protobuf package.Service name — this is how the router maps incoming gRPC calls to your handler.

3. Implement the service

<?php
// app/Grpc/GreeterService.php

namespace App\Grpc;

use App\Proto\Greeter\GreeterInterface;
use App\Proto\Greeter\HelloReply;
use App\Proto\Greeter\HelloRequest;

class GreeterService implements GreeterInterface
{
    public function SayHello(HelloRequest $in): HelloReply
    {
        $reply = new HelloReply();
        $reply->setMessage("Hello, {$in->getName()}!");
        return $reply;
    }

    public function SayGoodbye(HelloRequest $in): HelloReply
    {
        $reply = new HelloReply();
        $reply->setMessage("Goodbye, {$in->getName()}!");
        return $reply;
    }
}

The GrpcRouter auto-detects protobuf-typed parameters and handles mergeFromString() / serializeToString() automatically. You work with typed objects, not raw bytes.

4. Register in config

// config/folk.php

return [
    'grpc' => [
        'services' => [
            \App\Proto\Greeter\GreeterInterface::class => \App\Grpc\GreeterService::class,
        ],
    ],
];

That's it. FolkServiceProvider reads the config, resolves services from the Laravel container, and registers them with the GrpcRouter.

Accessing metadata in typed handlers

Add Context as the first parameter:

use Folk\Sdk\Grpc\Context;

class GreeterService implements GreeterInterface
{
    public function SayHello(Context $ctx, HelloRequest $in): HelloReply
    {
        $token = $ctx->getValue('authorization');
        // ...
    }
}

The router detects Context parameters automatically and injects the metadata.

Multiple services

Register as many services as you need:

// config/folk.php

'grpc' => [
    'services' => [
        \App\Proto\Greeter\GreeterInterface::class => \App\Grpc\GreeterService::class,
        \App\Proto\Auth\AuthInterface::class       => \App\Grpc\AuthService::class,
        \App\Proto\Orders\OrdersInterface::class   => \App\Grpc\OrdersService::class,
    ],
],

Compatibility with Spiral/RoadRunner

If you have services generated by protoc-gen-php-grpc (Spiral), they work with Folk:

// Spiral-generated interface
interface InfoInterface extends \Spiral\RoadRunner\GRPC\ServiceInterface
{
    public const NAME = "myapp.Info";
    public function Get(\Spiral\RoadRunner\GRPC\ContextInterface $ctx, \Google\Protobuf\GPBEmpty $in): ServiceInfo;
}

// Register as-is — Folk injects its own Context for the $ctx parameter
'services' => [
    InfoInterface::class => InfoService::class,
],

The NAME constant is read from any interface the handler implements. Context parameters (regardless of type) receive Folk's Context instance.

Testing with curl

# Encode HelloRequest { name: "Folk" } as protobuf
# Field 1 (string): 0x0a + length + bytes
printf '\x00\x00\x00\x00\x06\x0a\x04Folk' | curl --http2-prior-knowledge \
  -X POST http://localhost:50051/greeter.Greeter/SayHello \
  -H "content-type: application/grpc" \
  -H "authorization: Bearer my-token" \
  --data-binary @- -o response.bin

# Decode response (skip 5-byte gRPC frame)
python3 -c "
data = open('response.bin','rb').read()
proto = data[5:]
print(proto[2:2+proto[1]].decode())
"
# Output: Hello, Folk!

Testing with grpcurl

# List services (requires -proto flag)
grpcurl -plaintext -proto proto/greeter.proto localhost:50051 list

# Describe a service
grpcurl -plaintext -proto proto/greeter.proto localhost:50051 describe greeter.Greeter

# Note: grpcurl RPC calls require HTTP/2 trailers support (in progress)

Requirements

• PHP: google/protobuf package (composer require google/protobuf)
• protoc for generating PHP message classes

License

MIT