在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

protocolbuffers/protobuf

菜单

PHP 和 Ruby 集成

相关源文件

本文档详细介绍了 Protocol Buffers 语言绑定在 PHP 和 Ruby 语言中的实现，这两种语言都利用 upb (μprotobuf) 核心进行高性能的消息处理、序列化和反序列化。

概述

Protocol Buffers 通过两种不同的实现方式为 PHP 和 Ruby 提供支持

  1. 纯语言实现 - 完全使用 PHP/Ruby 编写
  2. C 扩展 (基于 upb) - 使用 upb (μprotobuf) C 库实现的高性能原生扩展

这些实现使 PHP 和 Ruby 开发人员能够无缝地处理 Protocol Buffer 消息，提供消息创建、字段访问、序列化/反序列化和反射支持等功能。

架构

PHP 和 Ruby 与 Protocol Buffers 的集成遵循使用 upb 核心的相似模式

此架构中的关键组件

  • Protocol Compiler (protoc)：从 .proto 定义生成特定语言的代码
  • 生成的代码：表示 Protocol Buffer 消息的 PHP/Ruby 类
  • 语言扩展：连接语言运行时和 upb 的原生扩展 (php-upb 和 ruby-upb)
  • upb 核心：提供核心 Protocol Buffers 功能的轻量级 C 实现

来源： php/ext/google/protobuf/php-upb.c ruby/ext/google/protobuf_c/ruby-upb.c php/ext/google/protobuf/php-upb.h ruby/ext/google/protobuf_c/ruby-upb.h

共同的实现特性

PHP 和 Ruby 扩展共享这些关键特性

  1. 消息处理

    • 在语言对象和 upb 消息结构之间进行转换
    • 字段访问器和类型转换
    • 处理嵌套消息和重复字段
    • 默认值管理

  2. 序列化/反序列化

    • 二进制格式序列化/反序列化
    • JSON 格式支持
    • 高效解析和错误处理

  3. Arena 内存管理

    • 两个扩展都使用 upb 的 arena 分配
    • 与语言内存管理集成（PHP 引用计数/Ruby GC）
    • 高效的资源清理

  4. 反射支持

    • 访问消息和字段描述符
    • 动态消息检查和操作
    • 类型信息和验证

  5. 错误处理

    • 将 upb 错误状态转换为语言异常
    • 详细的错误消息和上下文

来源： php/ext/google/protobuf/php-upb.c567-609 ruby/ext/google/protobuf_c/ruby-upb.c567-609

PHP 实现

PHP 扩展实现位于 php/ext/google/protobuf 目录中，为 PHP 提供了完整的 Protocol Buffers 实现。

关键组件

PHP 扩展 (php-upb) 提供

  1. Protocol Buffers 的 PHP API

    • 遵循 PHP 命名约定的类和方法
    • 与 PHP 对象系统的集成
    • 与 PHP 动态类型兼容的类型处理

  2. 安装与使用

    • 可通过 Composer 包 (google/protobuf) 获取
    • 同时支持纯 PHP 和 C 扩展实现
    • 当扩展不可用时，自动回退到纯 PHP

  3. 性能优化

    • 比纯 PHP 有显著的性能提升
    • 通过 arena 分配实现高效的内存使用
    • 可能的零拷贝解析

来源： php/ext/google/protobuf/php-upb.c php/ext/google/protobuf/php-upb.h php/composer.json

Ruby 实现

Ruby 扩展实现位于 ruby/ext/google/protobuf_c 目录中，为 Protocol Buffers 提供了 Ruby 绑定。

关键组件

Ruby 扩展 (ruby-upb) 提供

  1. Protocol Buffers 的 Ruby API

    • 遵循 Ruby 习惯用法的类和方法
    • 与 Ruby 对象系统的集成
    • Protocol Buffers 和 Ruby 类型之间的类型转换

  2. 内存管理

    • 与 Ruby 垃圾回收器的集成
    • 妥善的资源清理
    • 高效的基于 Arena 的分配

  3. 错误处理

    • Protocol Buffer 错误的 Ruby 异常类
    • 详细的错误消息
    • Ruby 习惯用法中的错误传播

来源： ruby/ext/google/protobuf_c/ruby-upb.c ruby/ext/google/protobuf_c/ruby-upb.h

实现差异

虽然 PHP 和 Ruby 的实现共享相同的 upb 核心，但在几个关键方面有所不同

方面PHP 实现Ruby 实现
内存管理与 PHP 的引用计数集成与 Ruby 的垃圾回收器集成
API设计遵循 PHP 命名约定遵循 Ruby 的习惯用法和实践
错误处理使用 PHP 异常类使用 Ruby 异常类
类型转换PHP 特定的类型处理Ruby 特定的类型处理
扩展加载PHP 扩展加载机制Ruby gem 原生扩展系统

这些差异反映了每种语言生态系统的独特性和约定。

来源： php/ext/google/protobuf/php-upb.c373-394 ruby/ext/google/protobuf_c/ruby-upb.c373-394

JSON 支持

PHP 和 Ruby 实现都提供了全面的 JSON 支持

JSON 功能处理

  1. 从 JSON 反序列化

    • 将 JSON 文本解析为 Protocol Buffer 消息
    • JSON 和 Protocol Buffer 类型之间的类型转换
    • 无效 JSON 或类型不匹配时的错误处理

  2. 序列化为 JSON

    • 将 Protocol Buffer 消息转换为 JSON 文本
    • 字段名称转换 (camelCase/snake_case)
    • 特殊类型处理 (64 位整数、字节等)

这使得 JSON 系统与 Protocol Buffers 之间可以实现无缝互操作。

来源： php/ext/google/protobuf/php-upb.c626-1123 ruby/ext/google/protobuf_c/ruby-upb.c626-1123

性能考量

基于 upb 的 C 扩展比纯语言实现提供了显著的性能优势

  1. 序列化/反序列化速度

    • C 扩展在解析和序列化消息方面速度更快
    • 对大型消息或高吞吐量系统尤其有利

  2. 内存效率

    • 与纯语言实现相比，内存占用更少
    • 更高效的消息数据表示
    • 减少了垃圾回收压力

  3. 运营开销

    • 常见操作的 CPU 使用率更低
    • 字段访问和操作的开销更低
    • 更高效的嵌套消息处理

对于性能敏感型应用，强烈建议使用 C 扩展。

来源： php/ext/google/protobuf/php-upb.c227-232 ruby/ext/google/protobuf_c/ruby-upb.c227-232

与语言生态系统的集成

两种实现都与其各自的语言生态系统良好集成

PHP 集成

  • 可通过 Composer 包 google/protobuf 获取
  • 与标准的 PHP 开发工作流程兼容
  • 适用于流行的 PHP 框架和库
  • 支持纯 PHP 和 C 扩展模式

Ruby 集成

  • 可作为 Ruby gem 使用
  • 与标准的 Ruby 开发实践兼容
  • 适用于流行的 Ruby 框架和库
  • 支持纯 Ruby 和 C 扩展实现

这确保了 Protocol Buffers 可以轻松地集成到现有的 PHP 和 Ruby 项目中。

来源： php/composer.json .gitignore135-147 .gitignore169-177

结论

PHP 和 Ruby 的 Protocol Buffers 集成提供了高性能、内存高效的实现，使开发人员能够轻松地在这些语言中使用 Protocol Buffer 消息。通过利用 upb 核心，这两种实现都取得了出色的性能，同时为每种语言提供了自然、惯用的接口。

对于大多数应用来说，C 扩展提供了性能和易用性的最佳组合，而纯语言实现则为无法使用原生扩展的环境提供了兼容性。