README

Protobuf for PHP 是 PHP 语言对谷歌 Protocol Buffers 的实现，支持其二进制数据序列化，包括一个 protoc 插件，用于从 .proto 文件生成 PHP 类。

为了生成包含各种类型提示的 PHP 文件，以帮助 IDE 进行自动完成，付出了大量努力。因此，它不仅可以用于与 Protocol Buffers 服务进行通信，还可以作为数据对象的生成工具，无论最终序列化方式如何。

有关更多信息，请参阅包含的手册页。

要求

PHP 5.3
Pear 的 Console_CommandLine（用于 protoc 包装工具）
谷歌的 protoc 编译器版本 2.3 或更高
GMP 或 BC Math 扩展 ¹

¹ 仅在 int32、int64 或 fixed64 类型中的负值时需要。请参阅 已知问题 部分。

特性

工作

标准类型（数字、字符串、枚举、消息等）
可插拔序列化后端（编解码器）
- 标准二进制
- 标准文本格式 ¹
- PhpArray
- JSON
- ProtoJson（TagMap 和 Indexed 变体）
- XML
用于生成 PHP 类的 Protoc 编译器插件
扩展
未知字段
打包字段
反射
支持动态消息和注解
生成服务接口
在生成的文件中包含 .proto 文件中的注释
用于简单安装的 Pear 包

¹ 仅支持序列化

未来

速度优化代码生成模式
支持超过 PHP 本机限制的数字

示例用法

<?php
require_once 'DrSlump/Protobuf.php';
\DrSlump\Protobuf::autoload();

$person = new Tutorial\Person();
$person->name = 'DrSlump';
$person->setId(12);

$book = new Tutorial\AddressBook();
$book->addPerson($person);

// Use default codec
$data = $book->serialize();

// Use custom codec
$codec = new \DrSlump\Protobuf\Codec\Binary();
$data = $codec->encode($book);
// ... or ...
$data = $book->serialize($codec);

安装

使用 Pear 安装

pear channel-discover pear.pollinimini.net
pear install drslump/Protobuf-beta

您还可以通过在计算机上检出存储库的副本来获取最新版本。

已知问题

类型

PHP 在处理数字方面非常弱。已经应用了一些方法来减少 Protobuf 类型与 PHP 类型之间的不兼容性。

Protobuf 使用 IEEE 754 标准，用 64 位字存储 double 类型的浮点值，用 32 位字存储 float 类型的浮点值。PHP 本地支持 IEEE 754，尽管精度依赖于平台，但通常支持 64 位双精度浮点数。这意味着，如果您的 PHP 是用 64 位大小的双精度浮点数（或更大）编译的，那么您应该不会在用 Protobuf 编码和解码 float 和 double 类型的值时遇到任何问题。
在 PHP 中，整数值也是依赖于平台的。该库已经针对用 64 位整数编译的 PHP 二进制文件开发和测试过。理论上，无论 PHP 内部使用 32 位还是 64 位整数，编码和解码算法都应该工作，只是要注意，在 32 位整数的情况下，数字不能超过 PHP_INT_MAX 值（2147483647）。

尽管 Protobuf 支持无符号整数，但 PHP 不支持。实际上，超过编译的 PHP 最大整数（PHP_INT_MAX，64 位为 0x7FFFFFFFFFFFFFFF）的数字将被自动转换为双精度浮点数，这通常提供 53 位的小数精度，允许安全地处理高达 0x20000000000000（2^53）的数字，即使它们在 PHP 中表示为浮点数而不是整数。更高的数字可能会丢失精度或甚至返回一个 无穷大 值，请注意，库不会对这些数字进行检查，使用它们可能会产生意外的行为。

当将负值编码为 int32、int64 或 fixed64 类型时，需要您的 PHP 环境中提供大整数扩展 GMP 或 BC Math（后者仅适用于 64 位架构）。原因是当不使用 zigzag 编码这些负数时，二进制表示使用最高有效位作为符号，因此这些数字会超过 PHP 支持的最大值。库将检查这些条件，并会自动尝试使用 GMP 或 BC 来处理这些值。

字符串

二进制编解码器期望字符串使用 UTF-8 编码。PHP 本地不支持字符串编码，PHP 的字符串数据类型基本上是一个长度定界的字节流，因此将自动编码转换包含到库的编码和解码例程中并不简单。而不是尝试猜测或提供一个配置界面来指定编码，二进制编解码器将像处理 byte 类型一样处理 string 类型，将编码或解码的任务委托给您的应用程序。

内存使用

大型消息可能会很麻烦，因为库的建模方式不允许将消息作为流解析或序列化，相反，整个操作都是在内存中完成的，这允许更快的处理，但如果消息太大，可能会消耗过多的 RAM。

未知字段

由于不同的编解码器格式之间的线类型不同，因此不可能将一个编解码器中消耗的未知字段转换为另一个编解码器。这意味着，例如，当使用二进制编解码器消耗消息时，如果它包含未知字段，则它们在用 Json 编解码器序列化消息时将不会包含在内。

生成 PHP 类

生成工具设计为作为 protoc 插件运行，因此它应该与官方编译器支持的任何 proto 文件一起工作。

protoc --plugin=protoc-gen-php --php_out=./build tutorial.proto

为了使用proto文件中的非标准选项（例如php.namespace），您需要导入库中包含的php.proto文件。该文件的位置取决于您安装此库的位置。

protoc -I=./Protobuf-PHP/library/DrSlump/Protobuf/Compiler/protos \
       --plugin=protoc-gen-php --php_out=./build tutorial.proto

为了让您的生活更轻松，提供的protoc插件提供了一种额外的执行模式，其中它充当protoc调用的包装器。它将自动包含php.proto路径，因此您无需担心。

protoc-gen-php -o ./build tutorial.proto

许可协议

The MIT License

Copyright (c) 2011 Iván -DrSlump- Montes

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

rgooding / protobuf-php

维护者

详细信息