README

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

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

有关更多信息，请参阅包含的 man 页面。

要求

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

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

功能

工作

标准类型（数字、字符串、枚举、消息等）
可插拔的序列化后端（编解码器）
- 标准二进制格式
- 标准文本格式 ¹
- PhpArray
- JSON
- ProtoJson（TagMap 和 Indexed 变体）
- XML
Protoc 编译器插件以生成 PHP 类
扩展
未知字段
打包字段
反射
支持带有注解的动态消息
生成服务接口
在生成的文件中包含 .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 标准存储浮点值，对于 double 类型使用 64 位字，对于 float 类型使用 32 位。PHP 本身支持 IEEE 754，尽管精度取决于平台，但通常支持 64 位双精度浮点数。这意味着，如果您使用 64 位大小的双精度浮点数（或更大）编译了 PHP，您应该不会在 Protobuf 中编码和解码浮点数和双精度浮点数类型的值时遇到任何问题。
在PHP中，整型值也是平台相关的。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。

未知字段

由于不同编解码器格式的wire类型不同，因此不可能将一个编解码器中消耗的未知字段转换为另一个编解码器。这意味着，例如，当使用二进制编解码器消费消息时，如果其中包含未知字段，则在序列化消息时使用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.

rastor / protobuf-php

维护者

详细信息