# php-protobuf

**Repository Path**: FEIGE/php-protobuf

## Basic Information

- **Project Name**: php-protobuf
- **Description**: 纯PHP解析protobuf编码，无依赖
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# PHP-Protobuf

纯 PHP 实现的 Protobuf 消息编码解码库，无需依赖 protoc 编译器。

## 特性

- **零依赖**：纯 PHP 实现，无需安装任何扩展
- **完整支持**：支持 varint、fixed32/64、float、double、string、bytes 等数据类型
- **嵌套消息**：支持任意层级的嵌套消息编码解码
- **repeated 字段**：支持重复字段（包括 packed 格式）
- **map 字段**：支持 map<string,string>、map<string,int>、map<int,string> 等类型
- **枚举类型**：支持枚举字段的编码解码
- **ZigZag 编码**：支持 sint32、sint64 的 ZigZag 编码
- **两种编码方式**：支持手动链式编码和字段定义自动编码

## 安装

直接引入 PHP 文件即可使用：

```php
require_once 'ProtobufEncoder.php';
require_once 'ProtobufDecoder.php';
```

## 快速开始

### 基本编码解码

```php
<?php
require_once 'ProtobufEncoder.php';
require_once 'ProtobufDecoder.php';

// 定义结构对应: message User { int32 id = 1; string name = 2; }

// 编码
$encoder = new ProtobufEncoder();
$binary = $encoder
    ->writeVarint(1, 1001)
    ->writeString(2, '张三')
    ->build();

// 解码
$decoder = new ProtobufDecoder($binary);
$result = $decoder->decode();
// $result[1]['value'] === 1001
// $result[2]['value'] === '张三'
```

### 嵌套消息编码

```php
<?php
// 编码嵌套消息
$geo = (new ProtobufEncoder())
    ->writeDouble(1, 39.9042)
    ->writeDouble(2, 116.4074)
    ->build();

$addr = (new ProtobufEncoder())
    ->writeString(1, '北京')
    ->writeString(2, '长安街1号')
    ->writeVarint(3, 100000)
    ->writeMessage(4, $geo)
    ->build();

$user = (new ProtobufEncoder())
    ->writeVarint(1, 1001)
    ->writeString(2, '张三')
    ->writeMessage(6, $addr)
    ->build();
```

### 嵌套消息解码

```php
<?php
$decoder = new ProtobufDecoder($binary);
$fields = $decoder->decode();

// 解码嵌套消息
if (isset($fields[6])) {
    $address = ProtobufDecoder::decodeMessage($fields[6]['value']);
    // 解码三级嵌套
    if (isset($address[4])) {
        $geo = ProtobufDecoder::decodeMessage($address[4]['value']);
    }
}
```

### Packed 数组编码

```php
<?php
// packed repeated int32
$encoder->writePackedVarint(8, [100, 200, 300, 400]);

// packed repeated double
$encoder->writePackedDouble(9, [98.5, 87.3, 92.1]);
```

### Map 编码

```php
<?php
$encoder->writeMapStringString(10, ['role' => 'admin', 'level' => 'vip']);
```
### Map 解码

```php
<?php
// map
echo "\n--- Meta (map) ---\n";
if (isset($result[10]['values'])) {
    foreach ($result[10]['values'] as $entryRaw) {
        $entry = ProtobufDecoder::decodeMessage($entryRaw);
        echo $entry[1]['value'] . " => " . $entry[2]['value'] . "\n";
    }
}
```

### 通过字段定义自动编码

```php
<?php
$registry = [
    'messages' => [
        'User' => [
            1 => ['name' => 'id', 'type' => 'int32'],
            2 => ['name' => 'name', 'type' => 'string'],
            3 => ['name' => 'email', 'type' => 'string'],
        ],
    ],
];

$encoder = new ProtobufEncoder();
$encoder->encodeFields([
    'id' => 1001,
    'name' => '张三',
    'email' => 'test@example.com',
], $registry['messages']['User'], $registry);

$binary = $encoder->build();
```

## API 参考

### ProtobufEncoder

| 方法 | 说明 |
|------|------|
| `writeVarint($field, $value)` | 写入 Varint 类型 |
| `writeBool($field, $value)` | 写入布尔类型 |
| `writeSint($field, $value)` | 写入带 ZigZag 编码的有符号整数 |
| `writeFixed32($field, $value)` | 写入固定 32 位整数 |
| `writeFixed64($field, $value)` | 写入固定 64 位整数 |
| `writeFloat($field, $value)` | 写入浮点数 |
| `writeDouble($field, $value)` | 写入双精度浮点数 |
| `writeString($field, $value)` | 写入字符串 |
| `writeBytes($field, $value)` | 写入字节串 |
| `writeMessage($field, $nested)` | 写入嵌套消息 |
| `writePackedVarint($field, $values)` | 写入 packed varint 数组 |
| `writePackedDouble($field, $values)` | 写入 packed double 数组 |
| `writeMapStringString($field, $map)` | 写入 map<string,string> |
| `encodeFields($data, $fieldDefs, $registry)` | 通过字段定义自动编码 |
| `build()` | 生成最终二进制数据 |
| `reset()` | 重置编码器 |

### ProtobufDecoder

| 方法 | 说明 |
|------|------|
| `decode()` | 解码所有字段 |
| `static decodeZigZag($value)` | 解码 ZigZag 有符号整数 |
| `static decodeFloat($bits)` | 解码浮点数 |
| `static decodeDouble($bits)` | 解码双精度浮点数 |
| `static decodeMessage($data)` | 解码嵌套消息 |

## 支持的数据类型

- `int32`、`int64`、`uint32`、`uint64`
- `sint32`、`sint64`（ZigZag 编码）
- `fixed32`、`fixed64`、`sfixed32`、`sfixed64`
- `float`、`double`
- `bool`
- `string`、`bytes`
- `enum`
- `message`（嵌套消息）
- `repeated`（数组）
- `packed`（压缩数组）
- `map`

## 协议规范

本库遵循 [Protocol Buffers](https://developers.google.com/protocol-buffers/) 协议规范实现。

## 许可证

MIT License