# WebmanGRPC

**Repository Path**: endcms/webman-grpc

## Basic Information

- **Project Name**: WebmanGRPC
- **Description**: No description available
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-14
- **Last Updated**: 2025-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Webman gRPC Extension

A gRPC support package for Webman framework based on the official PHP gRPC extension, providing convenient gRPC server/client creation and communication, as well as HTTP to gRPC request conversion functionality.

## Features

- ✅ **Official gRPC Extension Support** - Based on PHP official gRPC extension, ensuring standard compatibility
- ✅ **Server Support** - Simplify gRPC service creation and management
- ✅ **Client Support** - Provide convenient gRPC client calling interface
- ✅ **HTTP to gRPC Conversion** - Support HTTP request to gRPC request conversion
- ✅ **Deep Webman Integration** - Seamless integration with Webman framework
- ✅ **Connection Pool Management** - Efficient gRPC connection pool management
- ✅ **Service Discovery** - Support service registration and discovery
- ✅ **Load Balancing** - Built-in load balancing strategies
- ✅ **Interceptor Support** - Support request/response interceptors
- ✅ **Streaming Support** - Support client, server and bidirectional streaming calls

## Installation

### 1. Install PHP Official gRPC Extension

```bash
# Install using PECL
pecl install grpc

# Or compile and install
git clone -b v1.42.0 https://github.com/grpc/grpc.git
cd grpc
git submodule update --init
mkdir -p cmake/build
cd cmake/build
cmake ../..
make
make install

# Add to php.ini
extension=grpc.so
```

### 2. Install via Composer

```bash
composer require endcms/webman-grpc
```

### 3. Publish Configuration

```bash
php webman plugin:install endcms/webman-grpc
```

### 4. Configure Process

Add gRPC process in `config/process.php`:

```php
return [
    // ... other process configurations
    
    'grpc' => [
        'handler' => \WebmanGrpc\Process::class,
        'listen' => 'grpc://0.0.0.0:50051',
        'count' => 4,
        'context' => [
            'ssl' => [
                'local_cert' => '',
                'local_pk' => '',
            ],
        ],
    ],
];
```

## Quick Start

### 1. Create Proto File

```protobuf
// helloworld.proto
syntax = "proto3";

package helloworld;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
  rpc SayHelloStream (HelloRequest) returns (stream HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}
```

### 2. Generate PHP Code

```bash
protoc --php_out=. --grpc_out=. --plugin=protoc-gen-grpc=/usr/local/bin/grpc_php_plugin helloworld.proto
```

### 3. Create gRPC Service

```php
<?php
// app/service/GreeterService.php

namespace App\Service;

use Helloworld\HelloRequest;
use Helloworld\HelloReply;
use WebmanGrpc\BaseService;

class GreeterService extends BaseService
{
    public function SayHello(HelloRequest $request): HelloReply
    {
        $reply = new HelloReply();
        $reply->setMessage('Hello, ' . $request->getName());
        
        return $reply;
    }
    
    public function SayHelloStream(HelloRequest $request): \Generator
    {
        for ($i = 0; $i < 3; $i++) {
            $reply = new HelloReply();
            $reply->setMessage('Hello, ' . $request->getName() . " ({$i})");
            yield $reply;
        }
    }
}
```

### 4. Register Service

Register service in `config/plugin/endcms/webman-grpc/app.php`:

```php
return [
    'enable' => true,
    'grpc' => [
        'enabled' => true,
        'services' => [
            'helloworld.Greeter' => [
                'class' => \App\Service\GreeterService::class,
            ],
        ],
    ],
];
```

### 5. Start Service

```bash
php start.php start
```

## Client Calls

### 1. Simple Call

```php
<?php

use WebmanGrpc\Client\GrpcClient;
use Helloworld\HelloRequest;
use Helloworld\HelloReply;

$client = new GrpcClient('127.0.0.1:50051');

$request = new HelloRequest();
$request->setName('Webman');

/** @var HelloReply $response */
$response = $client->call('helloworld.Greeter', 'SayHello', $request);

echo $response->getMessage(); // Output: Hello, Webman
```

### 2. Streaming Call

```php
<?php

use WebmanGrpc\Client\GrpcClient;
use Helloworld\HelloRequest;
use Helloworld\HelloReply;

$client = new GrpcClient('127.0.0.1:50051');

$request = new HelloRequest();
$request->setName('Webman');

/** @var \Generator $stream */
$stream = $client->stream('helloworld.Greeter', 'SayHelloStream', $request);

foreach ($stream as $response) {
    /** @var HelloReply $response */
    echo $response->getMessage() . "\n";
}
```

## HTTP to gRPC Conversion

### 1. Configure Routes

Configure HTTP to gRPC routes in `config/plugin/endcms/webman-grpc/app.php`:

```php
return [
    'enable' => true,
    'http_gateway' => [
        'enabled' => true,
        'routes' => [
            [
                'path' => '/api/hello',
                'method' => 'POST',
                'service' => 'helloworld.Greeter',
                'method' => 'SayHello',
                'request_transformer' => \App\Transformer\HelloRequestTransformer::class,
                'response_transformer' => \App\Transformer\HelloResponseTransformer::class,
            ],
        ],
    ],
];
```

### 2. Create Transformers

```php
<?php
// app/transformer/HelloRequestTransformer.php

namespace App\Transformer;

use WebmanGrpc\Transformer\RequestTransformerInterface;
use Helloworld\HelloRequest;
use support\Request;

class HelloRequestTransformer implements RequestTransformerInterface
{
    public function transform(Request $httpRequest): HelloRequest
    {
        $data = json_decode($httpRequest->rawBody(), true);
        
        $request = new HelloRequest();
        $request->setName($data['name'] ?? 'World');
        
        return $request;
    }
}
```

```php
<?php
// app/transformer/HelloResponseTransformer.php

namespace App\Transformer;

use WebmanGrpc\Transformer\ResponseTransformerInterface;
use Helloworld\HelloReply;
use support\Response;

class HelloResponseTransformer implements ResponseTransformerInterface
{
    public function transform(HelloReply $grpcResponse): Response
    {
        return json([
            'message' => $grpcResponse->getMessage()
        ]);
    }
}
```

### 3. Send HTTP Request

```bash
curl -X POST http://localhost:8787/api/hello \
  -H "Content-Type: application/json" \
  -d '{"name": "Webman"}'
```

## Advanced Usage

### 1. Interceptors

```php
<?php

use WebmanGrpc\Interceptor\ServerInterceptorInterface;
use Grpc\ServerContext;
use Google\Protobuf\Internal\Message;

class LoggingInterceptor implements ServerInterceptorInterface
{
    public function intercept(
        Message $request,
        ServerContext $context,
        callable $next
    ): Message {
        // Pre-request processing
        $startTime = microtime(true);
        
        // Call next interceptor or service method
        $response = $next($request, $context);
        
        // Post-request processing
        $duration = microtime(true) - $startTime;
        echo "Request processed in {$duration}s\n";
        
        return $response;
    }
}
```

### 2. Connection Pool Configuration

```php
// config/plugin/endcms/webman-grpc/app.php
return [
    'enable' => true,
    'grpc' => [
        'client' => [
            'connection_pool' => [
                'max_connections' => 10,
                'idle_timeout' => 60,
                'max_lifetime' => 300,
            ],
        ],
    ],
];
```

## Configuration Options

### gRPC Server Configuration

```php
'grpc' => [
    'server' => [
        'host' => '0.0.0.0',              // Listen address
        'port' => 50051,                   // Listen port
        'credentials' => null,              // SSL credentials
        'max_recv_msg_length' => 4194304,   // Max receive message length
        'max_send_msg_length' => 4194304,   // Max send message length
    ],
],
```

### gRPC Client Configuration

```php
'grpc' => [
    'client' => [
        'timeout' => 30,                   // Timeout in seconds
        'credentials' => null,              // SSL credentials
        'max_recv_msg_length' => 4194304,   // Max receive message length
        'max_send_msg_length' => 4194304,   // Max send message length
        'retry' => 3,                      // Retry count
        'backoff' => [                     // Backoff strategy
            'initial' => 100,              // Initial delay (ms)
            'max' => 1000,                 // Maximum delay (ms)
            'multiplier' => 2,             // Delay multiplier
        ],
    ],
],
```

## Performance Optimization

1. **Connection Reuse**: Use connection pool to reduce connection creation overhead
2. **Streaming**: Use streaming for large amounts of data to reduce memory usage
3. **Interceptors**: Use interceptors wisely to avoid unnecessary performance overhead
4. **Async Processing**: Use async processing to improve concurrency
5. **Caching**: Cache frequently accessed data

## Troubleshooting

### 1. Check gRPC Extension

```bash
php -m | grep grpc
```

### 2. Check Port Usage

```bash
netstat -tlnp | grep 50051
```

### 3. View Logs

```bash
tail -f runtime/logs/webman.log
```

## License

MIT License