allegro / php-protobuf
Google的Protocol Buffers for PHP
Requires
- php: >=5.3
- pear/console_commandline: ^1.2
This package is not auto-updated.
Last update: 2021-01-22 23:55:45 UTC
README
由于Google官方的Protocol Buffers支持PHP语言,维护此项目是不必要的。请参考Protocol Buffers以获取对PHP语言的支持。
PHP Protobuf - Google的Protocol Buffers for PHP
概述
Protocol Buffers是一种以高效且可扩展的格式编码结构化数据的方法。它可能用于文件格式和RPC协议。
PHP Protobuf是Google为PHP实现的Protocol Buffers,旨在提供高性能,包括一个protoc
插件,用于从.proto文件生成PHP类。解析(解析和序列化)工作由PHP扩展完成。
要求
- PHP 7.0或更高版本(对于PHP 5支持,请参阅php5分支)
- Pear的Console_CommandLine(用于protoc插件)
- Google的protoc编译器版本2.6或更高
入门
安装
-
克隆源代码
git clone https://github.com/allegro/php-protobuf
-
进入源代码目录
cd php-protobuf
-
构建和安装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位正整数类型。请注意,解析大整数值可能会导致得到意外结果。
Protocol Buffers类型映射到PHP类型如下(x86_64)
| Protocol Buffers | PHP |
| ---------------- | ------ |
| double | float |
| float | |
| ---------------- | ------ |
| int32 | int |
| int64 | |
| uint32 | |
| uint64 | |
| sint32 | |
| sint64 | |
| fixed32 | |
| fixed64 | |
| sfixed32 | |
| sfixed64 | |
| ---------------- | ------ |
| bool | bool |
| ---------------- | ------ |
| string | string |
| bytes | |
Protocol Buffers类型映射到PHP类型如下(x86)
| 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
。
已知问题
参考文献
致谢
- PHP7 支持 (Sergey)