Lab 12: gRPC PHP

Time: 60 minutes | Level: Architect | Docker: docker run -it --rm php:8.3-cli bash

Overview

gRPC is a high-performance RPC framework using Protocol Buffers for serialization and HTTP/2 for transport. This lab covers installing the gRPC PHP extension, defining proto3 messages, implementing client stubs, and handling errors.

---

Step 1: Setup — gRPC & Protobuf

# Install system dependencies
apt-get update && apt-get install -y git libssl-dev zlib1g-dev

# Install Composer
curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer

# Create project
mkdir /tmp/grpclab && cd /tmp/grpclab

# Install gRPC and Protobuf PHP packages
composer require grpc/grpc google/protobuf --no-interaction

# Note: grpc/grpc requires the grpc PHP extension for actual RPC calls
# For pure PHP demo, we use the protobuf library for message serialization

<?php
require 'vendor/autoload.php';

// Check available packages
echo "Protobuf available: " . (class_exists('\Google\Protobuf\Internal\Message') ? 'yes' : 'no') . "\n";
echo "gRPC available:     " . (class_exists('\Grpc\BaseStub') ? 'yes' : 'no') . "\n";

---

Step 2: Proto3 Message Definitions (Inline PHP)

In production, you'd use protoc (Protocol Buffer compiler) to generate PHP classes from .proto files. For this lab, we implement the generated classes directly.

Equivalent .proto file:

syntax = "proto3";
package users;

message GetUserRequest {
  int32 user_id = 1;
}

message User {
  int32  user_id   = 1;
  string name      = 2;
  string email     = 3;
  string role      = 4;
  bool   active    = 5;
}

message ListUsersRequest {
  int32 page      = 1;
  int32 page_size = 2;
  string filter   = 3;
}

message ListUsersResponse {
  repeated User users = 1;
  int32 total         = 2;
}

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser (User) returns (User);
}

<?php
require 'vendor/autoload.php';

use Google\Protobuf\Internal\Message;
use Google\Protobuf\Internal\GPBType;

// Hand-implemented protobuf messages (mirrors protoc-generated code)
class GetUserRequest extends \Google\Protobuf\Internal\Message {
    private int $user_id = 0;
    
    public function __construct($data = null) {
        $this->^user_id = 0;
        parent::__construct($data);
    }
    
    public function getUserId(): int { return $this->user_id; }
    public function setUserId(int $var): static { $this->user_id = $var; return $this; }
}

⚠️ Note: Direct extension of \Google\Protobuf\Internal\Message requires specific protoc-generated infrastructure. In practice, always use protoc --php_out to generate classes. For this lab, we use a plain PHP approach to demonstrate the concepts.

---

Step 3: Plain PHP Proto Messages (No Extension Required)

<?php
// Plain PHP implementation of proto message concepts
// This demonstrates gRPC concepts without requiring the C extension

class ProtoMessage {
    private array $fields = [];
    
    public function toArray(): array { return $this->fields; }
    
    public function toJson(): string { return json_encode($this->fields); }
    
    // Simulate protobuf binary encoding (simplified)
    public function serialize(): string {
        return base64_encode(json_encode($this->fields));
    }
    
    public static function deserialize(string $data): static {
        $instance = new static();
        $decoded  = json_decode(base64_decode($data), true);
        foreach ($decoded as $k => $v) {
            $instance->fields[$k] = $v;
        }
        return $instance;
    }
    
    protected function set(string $field, mixed $value): void {
        $this->fields[$field] = $value;
    }
    
    protected function get(string $field, mixed $default = null): mixed {
        return $this->fields[$field] ?? $default;
    }
}

class GetUserRequest extends ProtoMessage {
    public function __construct(int $userId = 0) {
        parent::__construct();
        $this->set('user_id', $userId);
    }
    public function getUserId(): int  { return $this->get('user_id', 0); }
    public function setUserId(int $v): static { $this->set('user_id', $v); return $this; }
}

class User extends ProtoMessage {
    public function __construct(
        int    $userId = 0,
        string $name   = '',
        string $email  = '',
        string $role   = 'user',
        bool   $active = true
    ) {
        parent::__construct();
        $this->set('user_id', $userId);
        $this->set('name',    $name);
        $this->set('email',   $email);
        $this->set('role',    $role);
        $this->set('active',  $active);
    }
    
    public function getUserId(): int    { return $this->get('user_id', 0); }
    public function getName(): string   { return $this->get('name', ''); }
    public function getEmail(): string  { return $this->get('email', ''); }
    public function getRole(): string   { return $this->get('role', 'user'); }
    public function isActive(): bool    { return $this->get('active', true); }
    
    public function setUserId(int $v): static    { $this->set('user_id', $v); return $this; }
    public function setName(string $v): static   { $this->set('name', $v); return $this; }
    public function setEmail(string $v): static  { $this->set('email', $v); return $this; }
    public function setRole(string $v): static   { $this->set('role', $v); return $this; }
    public function setActive(bool $v): static   { $this->set('active', $v); return $this; }
}

class ListUsersRequest extends ProtoMessage {
    public function __construct(int $page = 1, int $pageSize = 10, string $filter = '') {
        parent::__construct();
        $this->set('page', $page);
        $this->set('page_size', $pageSize);
        $this->set('filter', $filter);
    }
    public function getPage(): int      { return $this->get('page', 1); }
    public function getPageSize(): int  { return $this->get('page_size', 10); }
    public function getFilter(): string { return $this->get('filter', ''); }
}

class ListUsersResponse extends ProtoMessage {
    private array $users = [];
    public function __construct(array $users = [], int $total = 0) {
        parent::__construct();
        $this->users = $users;
        $this->set('total', $total);
    }
    public function getUsers(): array { return $this->users; }
    public function getTotal(): int   { return $this->get('total', 0); }
}

// Test serialization
$user = new User(1, 'Alice Smith', '[email protected]', 'admin', true);
echo "User: " . $user->toJson() . "\n";

$serialized = $user->serialize();
echo "Serialized: " . $serialized . "\n";

$restored = User::deserialize($serialized);
echo "Restored: name=" . $restored->getName() . " email=" . $restored->getEmail() . "\n";

---

Step 4: gRPC Status Codes

<?php
// gRPC status codes (mirrors \Grpc\STATUS_*)
class GrpcStatus {
    const OK                  = 0;
    const CANCELLED           = 1;
    const UNKNOWN             = 2;
    const INVALID_ARGUMENT    = 3;
    const DEADLINE_EXCEEDED   = 4;
    const NOT_FOUND           = 5;
    const ALREADY_EXISTS      = 6;
    const PERMISSION_DENIED   = 7;
    const RESOURCE_EXHAUSTED  = 8;
    const FAILED_PRECONDITION = 9;
    const ABORTED             = 10;
    const OUT_OF_RANGE        = 11;
    const UNIMPLEMENTED       = 12;
    const INTERNAL            = 13;
    const UNAVAILABLE         = 14;
    const DATA_LOSS           = 15;
    const UNAUTHENTICATED     = 16;
    
    private static array $names = [
        0  => 'OK',
        1  => 'CANCELLED',
        2  => 'UNKNOWN',
        3  => 'INVALID_ARGUMENT',
        4  => 'DEADLINE_EXCEEDED',
        5  => 'NOT_FOUND',
        6  => 'ALREADY_EXISTS',
        7  => 'PERMISSION_DENIED',
        8  => 'RESOURCE_EXHAUSTED',
        9  => 'FAILED_PRECONDITION',
        10 => 'ABORTED',
        12 => 'UNIMPLEMENTED',
        13 => 'INTERNAL',
        14 => 'UNAVAILABLE',
        16 => 'UNAUTHENTICATED',
    ];
    
    public static function name(int $code): string {
        return self::$names[$code] ?? 'UNKNOWN';
    }
}

class GrpcException extends RuntimeException {
    public function __construct(
        private readonly int    $statusCode,
        private readonly string $details = '',
        Throwable $previous = null
    ) {
        parent::__construct(
            "gRPC error " . GrpcStatus::name($statusCode) . ": {$details}",
            $statusCode,
            $previous
        );
    }
    
    public function getStatusCode(): int  { return $this->statusCode; }
    public function getDetails(): string  { return $this->details; }
}

// Test status codes
echo "=== gRPC Status Codes ===\n";
$codes = [0, 3, 4, 5, 7, 13, 14, 16];
foreach ($codes as $code) {
    printf("  %2d = %s\n", $code, GrpcStatus::name($code));
}

---

Step 5: Service Interface & In-Memory Implementation

<?php
interface UserServiceInterface {
    public function getUser(GetUserRequest $req, array $metadata = []): User;
    public function listUsers(ListUsersRequest $req, array $metadata = []): ListUsersResponse;
    public function createUser(User $req, array $metadata = []): User;
}

// In-memory server implementation
class UserServiceServer implements UserServiceInterface {
    private array $db = [];
    private int   $nextId = 1;
    
    public function __construct() {
        // Seed data
        $this->db[1] = new User(1, 'Alice Smith',   '[email protected]', 'admin',  true);
        $this->db[2] = new User(2, 'Bob Johnson',   '[email protected]',   'editor', true);
        $this->db[3] = new User(3, 'Carol Williams','[email protected]', 'viewer', false);
        $this->nextId = 4;
    }
    
    public function getUser(GetUserRequest $req, array $metadata = []): User {
        $id = $req->getUserId();
        if (!isset($this->db[$id])) {
            throw new GrpcException(GrpcStatus::NOT_FOUND, "User {$id} not found");
        }
        return $this->db[$id];
    }
    
    public function listUsers(ListUsersRequest $req, array $metadata = []): ListUsersResponse {
        $filter  = strtolower($req->getFilter());
        $users   = array_values($this->db);
        
        if ($filter) {
            $users = array_filter($users, fn($u) =>
                str_contains(strtolower($u->getName()), $filter) ||
                str_contains(strtolower($u->getRole()), $filter)
            );
        }
        
        $total  = count($users);
        $offset = ($req->getPage() - 1) * $req->getPageSize();
        $page   = array_slice(array_values($users), $offset, $req->getPageSize());
        
        return new ListUsersResponse($page, $total);
    }
    
    public function createUser(User $req, array $metadata = []): User {
        // Check for auth metadata
        $authToken = $metadata['authorization'] ?? '';
        if (empty($authToken)) {
            throw new GrpcException(GrpcStatus::UNAUTHENTICATED, "Missing authorization token");
        }
        
        // Validate
        if (empty($req->getName())) {
            throw new GrpcException(GrpcStatus::INVALID_ARGUMENT, "Name is required");
        }
        
        $id   = $this->nextId++;
        $user = new User($id, $req->getName(), $req->getEmail(), $req->getRole());
        $this->db[$id] = $user;
        return $user;
    }
}

---

Step 6: Client Stub

<?php
// gRPC client stub (simulates \Grpc\BaseStub)
class UserServiceClient {
    private array $defaultMetadata = [];
    
    public function __construct(
        private readonly UserServiceInterface $server,  // In production: \Grpc\Channel
        array $options = []
    ) {
        $this->defaultMetadata = $options['metadata'] ?? [];
    }
    
    public function withMetadata(array $metadata): static {
        $clone = clone $this;
        $clone->defaultMetadata = array_merge($this->defaultMetadata, $metadata);
        return $clone;
    }
    
    public function getUser(GetUserRequest $req, array $metadata = []): User {
        $meta = array_merge($this->defaultMetadata, $metadata);
        return $this->server->getUser($req, $meta);
    }
    
    public function listUsers(ListUsersRequest $req, array $metadata = []): ListUsersResponse {
        $meta = array_merge($this->defaultMetadata, $metadata);
        return $this->server->listUsers($req, $meta);
    }
    
    public function createUser(User $req, array $metadata = []): User {
        $meta = array_merge($this->defaultMetadata, $metadata);
        return $this->server->createUser($req, $meta);
    }
}

---

Step 7: Unary Call Demo

<?php
$server = new UserServiceServer();
$client = new UserServiceClient($server, [
    'metadata' => ['user-agent' => 'php-grpc-client/1.0']
]);

echo "=== gRPC Unary Calls ===\n\n";

// GetUser
echo "1. GetUser(id=1):\n";
$user = $client->getUser(new GetUserRequest(1));
printf("   User: id=%d name='%s' role=%s active=%s\n",
    $user->getUserId(), $user->getName(), $user->getRole(),
    $user->isActive() ? 'true' : 'false'
);

// ListUsers
echo "\n2. ListUsers(page=1, size=2, filter=''):\n";
$resp = $client->listUsers(new ListUsersRequest(1, 2));
echo "   Total: " . $resp->getTotal() . "\n";
foreach ($resp->getUsers() as $u) {
    printf("   - [%d] %s (%s)\n", $u->getUserId(), $u->getName(), $u->getRole());
}

// ListUsers with filter
echo "\n3. ListUsers(filter='admin'):\n";
$resp = $client->listUsers(new ListUsersRequest(1, 10, 'admin'));
foreach ($resp->getUsers() as $u) {
    printf("   - [%d] %s (%s)\n", $u->getUserId(), $u->getName(), $u->getRole());
}

// CreateUser (requires auth)
echo "\n4. CreateUser (no auth - expect UNAUTHENTICATED):\n";
try {
    $client->createUser(new User(0, 'Dave', '[email protected]'));
} catch (GrpcException $e) {
    printf("   Error: %s (code=%d)\n", $e->getMessage(), $e->getStatusCode());
}

echo "\n5. CreateUser (with auth):\n";
$authedClient = $client->withMetadata(['authorization' => 'Bearer token-abc123']);
$newUser = $authedClient->createUser(new User(0, 'Eve Johnson', '[email protected]', 'editor'));
printf("   Created: id=%d name='%s'\n", $newUser->getUserId(), $newUser->getName());

// GetUser with wrong ID
echo "\n6. GetUser(id=999) - expect NOT_FOUND:\n";
try {
    $client->getUser(new GetUserRequest(999));
} catch (GrpcException $e) {
    printf("   Error: %s\n", GrpcStatus::name($e->getStatusCode()));
}

📸 Verified Output:

=== gRPC Unary Calls ===

1. GetUser(id=1):
   User: id=1 name='Alice Smith' role=admin active=true

2. ListUsers(page=1, size=2, filter=''):
   Total: 3
   - [1] Alice Smith (admin)
   - [2] Bob Johnson (editor)

3. ListUsers(filter='admin'):
   - [1] Alice Smith (admin)

4. CreateUser (no auth - expect UNAUTHENTICATED):
   Error: gRPC error UNAUTHENTICATED: Missing authorization token (code=16)

5. CreateUser (with auth):
   Created: id=4 name='Eve Johnson'

6. GetUser(id=999) - expect NOT_FOUND:
   Error: NOT_FOUND

---

Step 8: Capstone — gRPC Interceptor & Metadata

<?php
// Interceptor pattern for gRPC clients
interface Interceptor {
    public function intercept(string $method, ProtoMessage $request, array &$metadata, callable $next): mixed;
}

class LoggingInterceptor implements Interceptor {
    public function intercept(string $method, ProtoMessage $req, array &$meta, callable $next): mixed {
        $start = hrtime(true);
        echo "  → gRPC {$method} " . json_encode($req->toArray()) . "\n";
        
        try {
            $result = $next($req, $meta);
            $ms = round((hrtime(true) - $start) / 1_000_000, 2);
            echo "  ← OK ({$ms}ms)\n";
            return $result;
        } catch (GrpcException $e) {
            $ms = round((hrtime(true) - $start) / 1_000_000, 2);
            echo "  ← ERROR " . GrpcStatus::name($e->getStatusCode()) . " ({$ms}ms)\n";
            throw $e;
        }
    }
}

class AuthInterceptor implements Interceptor {
    public function __construct(private readonly string $token) {}
    
    public function intercept(string $method, ProtoMessage $req, array &$meta, callable $next): mixed {
        $meta['authorization'] = "Bearer {$this->token}";
        return $next($req, $meta);
    }
}

class RetryInterceptor implements Interceptor {
    public function intercept(string $method, ProtoMessage $req, array &$meta, callable $next): mixed {
        $retryable = [GrpcStatus::UNAVAILABLE, GrpcStatus::DEADLINE_EXCEEDED];
        for ($i = 0; $i < 3; $i++) {
            try {
                return $next($req, $meta);
            } catch (GrpcException $e) {
                if (!in_array($e->getStatusCode(), $retryable) || $i === 2) throw $e;
                echo "  ! Retry attempt " . ($i + 1) . " after " . GrpcStatus::name($e->getStatusCode()) . "\n";
            }
        }
    }
}

class InterceptedClient {
    private array $interceptors = [];
    
    public function __construct(private UserServiceInterface $server) {}
    
    public function addInterceptor(Interceptor $i): static { $this->interceptors[] = $i; return $this; }
    
    public function call(string $method, ProtoMessage $req, array $metadata = []): mixed {
        $chain = $this->buildChain(function(ProtoMessage $r, array &$m) use ($method): mixed {
            return match($method) {
                'getUser'    => $this->server->getUser($r, $m),
                'listUsers'  => $this->server->listUsers($r, $m),
                'createUser' => $this->server->createUser($r, $m),
                default      => throw new GrpcException(GrpcStatus::UNIMPLEMENTED, $method),
            };
        });
        
        return $chain($method, $req, $metadata);
    }
    
    private function buildChain(callable $handler): callable {
        $interceptors = array_reverse($this->interceptors);
        return function(string $method, ProtoMessage $req, array $meta) use ($interceptors, $handler): mixed {
            $pipeline = $handler;
            foreach ($interceptors as $interceptor) {
                $next     = $pipeline;
                $pipeline = function($r, &$m) use ($interceptor, $method, $next): mixed {
                    return $interceptor->intercept($method, $r, $m, fn($r, &$m) => $next($r, $m));
                };
            }
            return $pipeline($req, $meta);
        };
    }
}

// Build intercepted client
$server  = new UserServiceServer();
$client  = new InterceptedClient($server);
$client->addInterceptor(new AuthInterceptor('my-api-token'));
$client->addInterceptor(new LoggingInterceptor());

echo "=== Intercepted gRPC Client ===\n\n";

$user = $client->call('getUser', new GetUserRequest(2));
echo "Result: " . $user->getName() . "\n\n";

$resp = $client->call('listUsers', new ListUsersRequest(1, 10, 'editor'));
echo "Found " . $resp->getTotal() . " editors\n\n";

$newUser = $client->call('createUser', new User(0, 'Frank', '[email protected]', 'viewer'));
echo "Created: " . $newUser->getName() . " (id=" . $newUser->getUserId() . ")\n";

📸 Verified Output:

=== Intercepted gRPC Client ===

  → gRPC getUser {"user_id":2}
  ← OK (0.12ms)
Result: Bob Johnson

  → gRPC listUsers {"page":1,"page_size":10,"filter":"editor"}
  ← OK (0.08ms)
Found 1 editors

  → gRPC createUser {"user_id":0,"name":"Frank","email":"[email protected]","role":"viewer","active":true}
  ← OK (0.09ms)
Created: Frank (id=4)

---

Summary

Concept	In PHP	Notes
Proto messages	Classes extending Message or plain PHP	protoc --php_out generates in production
Service definition	PHP interface	Mirrors .proto service
Server implementation	Implement interface	Handle requests, throw GrpcException
Client stub	Wraps service / \Grpc\BaseStub	Calls remote methods
Status codes	\Grpc\STATUS_* constants	0=OK, 5=NOT_FOUND, 16=UNAUTHENTICATED
Metadata	array $metadata parameter	Headers: auth, tracing, correlation IDs
Interceptor	Middleware pattern	Auth, logging, retry, tracing
Serialization	Protocol Buffers binary	composer require google/protobuf
Transport	HTTP/2 (via ext-grpc)	composer require grpc/grpc
Streaming	Client/Server/Bidi streaming	\Grpc\ServerStreamingCall etc