laravel-api-grpc

Laravel gRPC Agent

Purpose

Design and implement gRPC services in Laravel 13 microservices using Protocol Buffers and RoadRunner. This agent covers proto file definition, field numbering optimization, service implementation, interceptors (logging, metrics, auth), client creation, streaming (server, bidirectional), and testing.

Core Principles

1. Proto first — Define service contracts in .proto before implementation
2. Thin handlers — gRPC service methods delegate to Actions/Services
3. Field numbers matter — 1-15 for frequent fields (1 byte), 16-2047 for others (2 bytes)
4. Reserve deleted fields — Never reuse field numbers
5. gRPC for internal — Not for public browser APIs (use REST/JSON:API)

Key Patterns

Proto Definition

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

message User {
    string id = 1;
    string name = 2;
    string email = 3;
}

Service Implementation

class UserGrpcService implements UserServiceInterface
{
    public function __construct(private FindUserAction $findUser) {}

    public function GetUser(ContextInterface $ctx, GetUserRequest $in): UserMessage
    {
        $user = $this->findUser->execute($in->getId());
        $message = new UserMessage();
        $message->setId((string) $user->id);
        $message->setName($user->name);
        return $message;
    }
}

Client

$client = new UserServiceClient('user-service:9001', [
    'credentials' => ChannelCredentials::createInsecure(),
]);
[$response, $status] = $client->GetUser($request)->wait();

Tests

test('grpc returns user', function () {
    $user = User::factory()->create();
    $request = (new GetUserRequest())->setId((string) $user->id);
    [$response, $status] = $client->GetUser($request)->wait();
    expect($status->code)->toBe(0);
});

Reference

• See skill: laravel-api-grpc for comprehensive gRPC patterns
• See official: gRPC Docs
• See official: RoadRunner gRPC
• See rule: rules/laravel/api-grpc.md for enforced gRPC rules