README

⚠️ 该扩展可以在 Windows 下构建（可以使用 WSL），但我还没有弄清楚如何做到这一点，在这个分支中，所有内容都转换为属性，因为 PHP 8 中不能创建动态属性。

🙌 make test 通过测试

Composer 包： https://packagist.org.cn/packages/tankonyako/php-protobuf

此存储库不再维护

由于 Google 的官方 Protocol Buffers 支持 PHP 语言，维护此项目是不合理的。请参阅 Protocol Buffers 了解 PHP 语言支持。

PHP Protobuf - Google 的 Protocol Buffers for PHP

概述

Protocol Buffers 是一种高效且可扩展的格式，用于编码结构化数据。它可能用于文件格式和 RPC 协议。

PHP Protobuf 是 Google 为 PHP 实现的 Protocol Buffers，旨在提供高性能，包括一个从 .proto 文件生成 PHP 类的 protoc 插件。解析（解析和序列化）的重负载由 PHP 扩展完成。

要求

PHP 8.0 或更高版本（对于 PHP 7 支持，请参阅 php5 分支）
Pear 的 Console_CommandLine（用于 protoc 插件）
Google 的 protoc 编译器版本 2.6 或更高

入门

安装

克隆源代码

git clone https://github.com/Tankonyako/php-protobuf-php8

转到源代码目录
```
cd php-protobuf-php8
```
构建和安装 PHP 扩展（遵循 php.net 上的说明）
安装 protoc 插件依赖项
```
composer install
```

用法

假设您有一个文件 foo.proto

message Foo
{
    required int32 bar = 1;
    optional string baz = 2;
    repeated float spam = 3;
}

编译 foo.proto
```
php protoc-gen-php.php foo.proto
```

创建 Foo 消息并填充一些数据

require_once 'Foo.php';

$foo = new Foo();
$foo->setBar(1);
$foo->setBaz('two');
$foo->appendSpam(3.0);
$foo->appendSpam(4.0);

将消息序列化为字符串
```
$packed = $foo->serializeToString();
```

从字符串解析消息

$parsedFoo = new Foo();
try {
    $parsedFoo->parseFromString($packed);
} catch (Exception $ex) {
    die('Oops.. there is a bug in this example, ' . $ex->getMessage());
}

让我们看看我们解析了什么

$parsedFoo->dump();

应该产生类似以下输出

Foo {
  1: bar => 1
  2: baz => 'two'
  3: spam(2) =>
    [0] => 3
    [1] => 4
}

如果您愿意，可以将对象重置为其初始状态
```
$parsedFoo->reset();
```

指南

编译

PHP Protobuf 附带 Google 的 protoc 编译器插件。您可以直接运行它

php protoc-gen-php.php -o output_dir foo.proto

或将其传递给 protoc

protoc --plugin=protoc-gen-allegrophp=protoc-gen-php.php --allegrophp_out=output_dir foo.proto

在 Windows 上使用 protoc-gen-php.bat 代替。

命令行选项

-o out, --out=out - 生成文件的目标目录（默认为当前目录）。
-I proto_path, --proto_path=proto_path - 搜索导入的目录。
--protoc=protoc - protoc 编译器可执行文件路径。
-D define, --define=define - 定义生成器选项（例如 -Dnamespace='Foo\Bar\Baz'）。

生成器选项

namespace - 生成 PHP 类要使用的命名空间。

消息类

编译期间生成的类遵循 PSR-0 合规性（每个类都放入其自己的文件）。如果未定义 namespace 生成器选项，则使用包名（如果存在）来创建命名空间。如果没有设置包名，则将类放入全局空间。

PHP Protobuf模块实现了ProtobufMessage类，该类封装了协议逻辑。由proto文件编译的消息扩展了这个类，提供了消息字段描述符。基于这些描述符，ProtobufMessage知道如何解析和序列化给定类型的消息。

为每个字段生成一组访问器。针对单值字段（required / optional）和多值字段（repeated），方法集合不同。

required / optional

  get{FIELD}()        // return a field value
  has{FIELD}()        // check whether a field is set
  set{FIELD}($value)  // set a field value to $value

repeated

  append{FIELD}($value)       // append $value to a field
  clear{FIELD}()              // empty field
  get{FIELD}()                // return an array of field values
  getAt{FIELD}($index)        // return a field value at $index index
  getCount{FIELD}()           // return a number of field values
  has{FIELD}()                // check whether a field is set
  getIterator{FIELD}()        // return an ArrayIterator

{FIELD}是一个驼峰命名的字段名。

枚举

PHP原生不支持枚举类型。因此，枚举以PHP整型类型表示。为了方便，枚举被编译成一个类，其中包含与可能值对应的常量集。

类型映射

可用的内置PHP类型范围有限制。PHP不支持64位正整数类型。请注意，解析大整数值可能会得到意外的结果。

以下（x86_64）是Protocol Buffers类型映射到PHP类型的方式

| Protocol Buffers | PHP    |
| ---------------- | ------ |
| double           | float  |
| float            |        |
| ---------------- | ------ |
| int32            | int    |
| int64            |        |
| uint32           |        |
| uint64           |        |
| sint32           |        |
| sint64           |        |
| fixed32          |        |
| fixed64          |        |
| sfixed32         |        |
| sfixed64         |        |
| ---------------- | ------ |
| bool             | bool   |
| ---------------- | ------ |
| string           | string |
| bytes            |        |

以下（x86）是Protocol Buffers类型映射到PHP类型的方式

| Protocol Buffers | PHP                         |
| ---------------- | --------------------------- |
| double           | float                       |
| float            |                             |
| ---------------- | --------------------------- |
| int32            | int                         |
| uint32           |                             |
| sint32           |                             |
| fixed32          |                             |
| sfixed32         |                             |
| ---------------- | --------------------------- |
| int64            | if val <= PHP_INT_MAX       |
| uint64           | then value is stored as int |
| sint64           | otherwise as double         |
| fixed64          |                             |
| sfixed64         |                             |
| ---------------- | --------------------------- |
| bool             | bool                        |
| ---------------- | --------------------------- |
| string           | string                      |
| bytes            |                             |

未设置值用null类型表示。要取消设置值，只需将其值设置为null。

解析

要解析消息，创建一个消息类实例并调用其parseFromString方法，传入一个序列化的消息。遇到的错误通过抛出Exception来指示。异常消息提供了详细的说明。未设置的必需字段被静默忽略。

$packed = /* serialized FooMessage */;
$foo = new FooMessage();

try {
    $foo->parseFromString($packed);
} catch (Exception $ex) {
    die('Parse error: ' . $e->getMessage());
}

$foo->dump(); // see what you got

序列化

要序列化消息，调用serializeToString方法。它返回一个包含protobuf编码消息的字符串。遇到的错误通过抛出Exception来指示。异常消息提供了详细的说明。未设置的必需字段触发错误。

$foo = new FooMessage()
$foo->setBar(1);

try {
    $packed = $foo->serializeToString();
} catch (Exception $ex) {
    die 'Serialize error: ' . $e->getMessage();
}

/* do some cool stuff with protobuf-encoded $packed */

调试

可能会有需要调查给定消息实际内容的情况。在消息实例上var_dump给出的信息有些晦涩难懂。

ProtobufMessage类提供了一个dump方法，可以将消息内容打印到标准输出。它接受一个可选参数，指定是否只转储已设置的字段（默认情况下只转储已设置的字段）。传递false作为参数以转储所有字段。它产生的格式类似于var_dump。

或者，您可以使用printDebugString()方法，该方法以协议缓冲区文本格式产生输出。

IDE辅助工具和自动完成支持

要将此扩展与您的IDE（PhpStorm、Eclipse等）集成并获取自动完成支持，只需在项目根目录下任何位置包含stubs\ProtobufMessage.php即可。

已知问题

映射（maps）未完全支持（#73）
oneof（oneof）不支持（#72）
组（groups）不支持
扩展（extensions）不支持（#131）

参考文献

Protocol Buffers

致谢

PHP7支持（Sergey）

tankonyako / php-protobuf

维护者

详情