README

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

在生成包含各种类型提示的PHP文件上投入了大量精力，以帮助IDE进行自动完成。因此，它不仅可以用于与协议缓冲区服务进行通信，还可以作为任何最终序列化方式的数据对象的生成工具。

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

要求

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在处理数字时非常弱。已应用了多种解决方案来减少协议缓冲区类型和PHP类型之间的不兼容性。

Protobuf使用IEEE 754标准存储浮点值，对于double类型使用64位字，对于float类型使用32位。PHP原生支持IEEE 754，尽管精度取决于平台，但通常支持64位双精度浮点数。这意味着如果您的PHP是用64位大小的双精度浮点数（或更大）编译的，那么您应该没有问题使用协议缓冲区编码和解码浮点型和双精度型值。
整型值在PHP中也是平台相关的。该库已针对用64位整数编译的PHP二进制文件进行开发和测试。在理论上，编码和解码算法应该适用于PHP内部使用32位或64位整数，但请注意，使用32位整数时，数字不能超过PHP_INT_MAX值（2147483647）。

虽然 Protobuf 支持 unsigned integers，但 PHP 不支持。事实上，高于编译后的 PHP 最大整数（PHP_INT_MAX，64位为 0x7FFFFFFFFFFFFFFF）的数字将被自动转换为 double 类型，这通常提供 53 位的十进制精度，允许安全地处理高达 0x20000000000000（2^53）的数字，即使它们在 PHP 中以浮点数的形式表示。更高的数字可能会丢失精度，甚至可能返回 infinity 值，请注意，库不会对这些数字进行检查，使用它们可能会导致意外的行为。

当将负值编码为 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.

wedevbr / protobuf-php

维护者

详细信息