Grpcavel

Grpcavel is a gRPC framework for Laravel that focuses on developer experience. It uses a code-first approach to generate and compile protobuf files, meaning you don't have to write .proto definitions manually.

Why Grpcavel?

Building gRPC services in PHP is traditionally painful. Grpcavel makes it feel like building a standard Laravel API:

• Code-First: Your PHP classes are the source of truth. Protos are generated automatically.
• RoadRunner Runtime: Uses a persistent worker model for extreme performance.
• Laravel Native: Supports Laravel validation, middleware, and Eloquent out of the box.

Why Grpcavel over Node.js or Golang?

For many engineering teams, Laravel serves as the core application stack. Grpcavel was designed to empower PHP developers with the raw performance and efficiency of gRPC, eliminating the need to adopt new languages or fragment the technology stack solely for inter-service communication.

By leveraging RoadRunner's persistent worker architecture, Grpcavel delivers performance that challenges traditional PHP limitations. The goal is not to replace Go or Node.js, but to provide a seamless, high-performance gRPC implementation tailored specifically for the Laravel ecosystem.

Key Use Cases

• Enterprise Microservices: Orchestrate communication between distributed Laravel applications.
• High-Throughput Internal APIs: Build low-latency internal services.
• Optimized Backend Communication: Achieve faster serialization and transmission than traditional REST/JSON.
• Polyglot Integration: Connect Laravel services with other languages using strictly typed, auto-generated protobuf schemas.
• Real-time Systems Support: Provide a robust foundation for mobile backends and high-frequency systems.

Benchmarks

Grpcavel leverages RoadRunner's persistent worker model, yielding performance that significantly outpaces traditional PHP-FPM setups.

Here is a real benchmark conducted on a local development machine (Laptop) simulating a real-world scenario with Database Interaction (reading from SQLite):

Setup	Requests per Second (RPS)	Total Requests	Concurrency	Success Rate
Grpcavel (RoadRunner)	~140 RPS	1,000	50	100%

Benchmark Details

• Tool: ghz (gRPC load testing tool)
• Scenario: Fetching a user by ID from database via Eloquent.
• Hardware: Local development machine (Windows).
• Workers: 4 RoadRunner workers.

Note: This is a real-world benchmark involving database I/O. For simple "echo" or non-DB services, performance can reach thousands of requests per second.

Compatibility

Grpcavel is tested against multiple Laravel and PHP versions to ensure stability:

Laravel Version	PHP Version
10.x	8.2, 8.3
11.x	8.2, 8.3, 8.4
12.x	8.2, 8.3, 8.4
13.x	8.3, 8.4

Documentation

Full documentation is available at github.com/Fadhila36/grpcavel-docs.

Installation

You can install the package via composer:

composer require fadhila36/grpcavel

After installing, run the install command to prepare the environment:

php artisan grpc:install

Usage

1. Create a Service

Generate a new service class using Artisan:

php artisan grpc:make-service UserService

2. Define Methods

Annotate your service methods with #[GrpcMethod]. Each method must accept one request DTO and return one response DTO.

namespace App\Grpc\Services;

use Grpcavel\Attributes\GrpcService;
use Grpcavel\Attributes\GrpcMethod;
use App\Grpc\Requests\GetUserRequest;
use App\Grpc\Responses\UserResponse;

#[GrpcService]
class UserService
{
    #[GrpcMethod]
    public function getUser(GetUserRequest $request): UserResponse
    {
        $user = \App\Models\User::findOrFail($request->id);
        
        return UserResponse::fromModel($user);
    }
}

3. Validation

Define rules in your request DTO by extending GrpcRequest:

class GetUserRequest extends GrpcRequest
{
    public function __construct(public readonly int $id) {}

    public function rules(): array
    {
        return ['id' => 'required|integer|exists:users,id'];
    }
}

4. Synchronization

Sync your PHP definitions with .proto files and compile the stubs:

php artisan grpc:sync

5. Start the Server

Start the RoadRunner gRPC server:

php artisan grpc:start

Middleware

You can apply middleware to services or individual methods using attributes:

#[GrpcService]
#[Middleware(Authenticate::class)]
class SecureService {
    #[GrpcMethod]
    #[Middleware(LogRequest::class)]
    public function handle(...) {}
}

Enterprise Features

Rate Limiting

Protect your services from abuse using the built-in RateLimitMiddleware. Configure limits in config/grpc.php and apply it to your services:

#[GrpcService]
#[Middleware(\Grpcavel\Middleware\RateLimitMiddleware::class)]
class PublicService { ... }

Docker Support

Deploy with confidence using the included production-optimized Dockerfile. It handles PHP 8.3, RoadRunner binaries, and necessary extensions out of the box.

Client Scaffolding

Generate client-side wrappers to facilitate communication between microservices:

php artisan grpc:make-client UserServiceClient

Testing

Grpcavel provides a GrpcClient to test your services in-process:

$response = GrpcClient::call(UserService::class, 'getUser', new GetUserRequest(id: 1));

expect($response)->toBeInstanceOf(UserResponse::class);

Production Optimization

Service Discovery Cache

In production, you can cache your service definitions to avoid the overhead of scanning directories and using reflection:

php artisan grpc:cache

To clear the cache:

php artisan grpc:clear

Runtime Stability

Grpcavel is hardened for long-lived processes:

• Memory Management: Automatically flushes query logs and triggers garbage collection after each request.
• Database Resilience: Detects and recovers lost database connections between requests.

Commands Reference

Command	Description
grpc:install	Bootstrap directories and config.
grpc:sync	Generate and compile proto files.
grpc:compile	Manually compile proto files.
grpc:cache	Create service discovery cache.
grpc:clear	Remove service discovery cache.
grpc:start	Start the gRPC server.
grpc:make-service	Create a new service.
grpc:make-client	Create a client wrapper.
grpc:make-request	Create a request DTO.
grpc:make-response	Create a response DTO.

Support the Project

If you find Grpcavel helpful, please consider giving it a star ⭐ on GitHub! It helps more developers discover the project and motivates us to keep improving it.

Open Source & Contributing

Grpcavel is an open-source project, and we welcome contributions from the community! Whether it's reporting a bug, proposing a new feature, or submitting a Pull Request, your help is highly appreciated.

If you're interested in contributing, please feel free to fork the repository and submit a PR. For major changes, please open an issue first to discuss what you would like to change.

Credits

• Muhammad Fadhila Abiyyu Faris

License

The MIT License (MIT). Please see License File for more information.