allegro/php-protobuf

此包已被废弃且不再维护。未建议替代包。

Google的Protocol Buffers for PHP

v0.12.4 2019-01-07 10:55 UTC

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或更高

入门

安装

  1. 克隆源代码

    git clone https://github.com/allegro/php-protobuf
    
  2. 进入源代码目录

    cd php-protobuf
    
  3. 构建和安装PHP扩展(遵循php.net上的说明)

  4. 安装protoc插件依赖项

    composer install
    

用法

  1. 假设你有一个文件foo.proto

    message Foo
    {
        required int32 bar = 1;
        optional string baz = 2;
        repeated float spam = 3;
    }
    
  2. 编译foo.proto

    php protoc-gen-php.php foo.proto
    
  3. 创建Foo消息并用一些数据填充它

    require_once 'Foo.php';
    
    $foo = new Foo();
    $foo->setBar(1);
    $foo->setBaz('two');
    $foo->appendSpam(3.0);
    $foo->appendSpam(4.0);
  4. 将消息序列化为字符串

    $packed = $foo->serializeToString();
  5. 从字符串解析消息

    $parsedFoo = new Foo();
    try {
        $parsedFoo->parseFromString($packed);
    } catch (Exception $ex) {
        die('Oops.. there is a bug in this example, ' . $ex->getMessage());
    }
  6. 让我们看看我们解析了什么

    $parsedFoo->dump();

    应该产生类似以下内容的输出

    Foo {
      1: bar => 1
      2: baz => 'two'
      3: spam(2) =>
        [0] => 3
        [1] => 4
    }
    
  7. 如果你愿意,可以将对象重置为其初始状态

    $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

已知问题

  • maps 不完全支持 (#73)
  • oneof 不支持 (#72)
  • groups 不支持
  • extenions 不支持 (#131)

参考文献

致谢