bigdata-php 文档

环境要求

框架适配器的版本与 PHP 下限：

框架自身的 PHP 下限可能高于本包的 8.0；以框架要求为准。

安装

标准安装方式（Packagist 已上线）：

composer require erikwang2013/bigdata-php:^2.0

包在 Composer 中声明为 yii2-extension，以便 Yii2 自动注册组件；Laravel、ThinkPHP、Webman、Hyperf、Yii3 和非 Yii2 项目仍按普通 Composer 库安装。框架注册细节见第 6 节。

按需安装可选依赖：

composer require apache/thrift           # Hive / Spark Thrift Server
composer require mroosz/php-cassandra    # Cassandra

Doris / StarRocks 不需要额外的 Composer 包，但需要在 php.ini 中启用 pdo_mysql 扩展。

快速开始

use Erikwang2013\BigData\BigData;

$trino = BigData::driver('trino', [
    'host' => '127.0.0.1',
    'port' => 8080,
    'user' => 'php',
    'catalog' => 'hive',
    'schema' => 'default',
]);

$result = $trino->query('SELECT 1 AS id');

foreach ($result->rows() as $row) {
    echo $row[0], PHP_EOL;
}

ResultSet 的常用方法：

$result->columns(); // 列名或列描述，具体结构由驱动决定
$result->rows();    // 行数组，null 值原样保留
$result->count();   // 行数
$result->raw();     // 驱动原始返回，便于排查协议细节

调度类驱动示例：

$airflow = BigData::driver('airflow', [
    'baseUrl' => 'http://127.0.0.1:8081',
    'username' => 'admin',
    'password' => 'admin',
]);

$airflow->triggerDag('daily_etl', ['date' => '2026-10-29']);

可选驱动模式：

BigData::drivers();   // 全部 21 个驱动键
BigData::available(); // 当前环境可选依赖齐全的驱动键

try {
    $hive = BigData::driver('hive', ['host' => '127.0.0.1']);
} catch (\Erikwang2013\BigData\Exception\DriverUnavailableException $e) {
    echo $e->getMessage(); // 包含 composer require apache/thrift 提示
}

驱动也可以直接实例化。直接实例化不会经过可选依赖检查，缺少扩展或类时会在运行时失败：

use Erikwang2013\BigData\Driver\Trino\TrinoClient;
use Erikwang2013\BigData\Driver\Trino\TrinoConfig;

$trino = new TrinoClient(TrinoConfig::fromArray([
    'host' => '127.0.0.1',
]));

框架集成

核心包不依赖任何框架。src/Integration 中的适配器只做两件事：读取统一的 default / drivers 配置，把 Erikwang2013\BigData\Integration\Manager 绑定到框架容器。

每个适配器都有独立文档：Laravel、ThinkPHP、Webman、Hyperf、Yii2、Yii3。

首次启动时，适配器按框架约定自动复制配置模板：Laravel、ThinkPHP、Webman、Yii2 写入 config/bigdata.php，Hyperf 写入 config/autoload/bigdata.php；Yii3 由 yiisoft/config 自动合并包内配置，无需复制。已有配置文件不会被覆盖。

composer require 后的注册方式随框架规则不同：

统一配置结构（所有框架相同）：

// config/bigdata.php
return [
    'default' => 'trino',
    'drivers' => [
        'trino' => [
            'host' => '127.0.0.1',
            'port' => 8080,
            'user' => 'php',
            'catalog' => 'hive',
            'schema' => 'default',
        ],
        'airflow' => [
            'baseUrl' => 'http://127.0.0.1:8081',
            'username' => 'admin',
            'password' => 'admin',
        ],
    ],
];

Manager 的公开行为：

• driver() 使用 default，driver('airflow') 使用显式名称；同一名称的实例会被缓存。
• drivers() 返回 drivers 下已配置的驱动名。
• available() 返回已配置且可选依赖齐全的驱动名。
• 只允许创建 drivers 中配置过的驱动；未知名称抛出 InvalidArgumentException。

Laravel

包在 extra.laravel.providers 中声明服务提供者，composer require 后 Laravel 自动发现并注册，无需修改 config/app.php 或 bootstrap/providers.php。首次启动会自动写入 config/bigdata.php，已有文件不会被覆盖；也可以显式发布：

php artisan vendor:publish --tag=bigdata-config

使用：

$trino = app(\Erikwang2013\BigData\Integration\Manager::class)->driver('trino');

// provider 同时注册了 "bigdata" 别名
$airflow = app('bigdata')->driver('airflow');

ThinkPHP

包在 extra.think.services 中声明服务。使用 topthink/think 骨架时，composer require 触发的 post-autoload-dump 会自动执行 php think service:discover；旧项目或自定义骨架没有该脚本时，手动执行一次。首次启动会自动写入 config/bigdata.php，无需复制模板。

$manager = app('bigdata');
$trino = $manager->driver('trino');

Webman

包内置 Webman 插件安装器（src/Install.php）。composer require 时，Webman 骨架的 post-package-install 钩子会调用它，自动写入 config/plugin/erikwang2013/bigdata-php/app.php 和 bootstrap.php；Webman 启动时加载该配置并运行 Bootstrap。首次 worker 启动会自动写入 config/bigdata.php，无需手动改 config/bootstrap.php。

如果 Webman 的插件钩子被禁用，再手动注册：

// config/bootstrap.php
return [
    Erikwang2013\BigData\Integration\Webman\Bootstrap::class,
];

适配器使用懒加载定义，每个 worker 进程拥有自己的 Manager：

$manager = \support\Container::get(\Erikwang2013\BigData\Integration\Manager::class);
$trino = $manager->driver('trino');

Hyperf

包在 extra.hyperf.config 中声明 ConfigProvider，composer require 后自动参与配置提供者合并，无需手写 config_providers。首次启动会自动写入 config/autoload/bigdata.php；也可以显式发布：

php bin/hyperf.php vendor:publish erikwang2013/bigdata-php

Hyperf 3 需要 PHP 8.1 和 Swoole 5：

$manager = $container->get(\Erikwang2013\BigData\Integration\Manager::class);
$trino = $manager->driver('trino');

Yii2

本包声明为 type=yii2-extension，并在 extra.bootstrap 中注册 BigDataBootstrap。yiisoft/yii2-composer 会把组件自动加入应用，无需修改 config/web.php 或 config/console.php；组件首次使用会自动写入 config/bigdata.php。非 Yii2 项目仍由 Composer 的默认安装器按普通库安装，不受影响。

如果 Yii2 的 Composer 插件被禁用，再手动注册组件：

// config/web.php
return [
    'components' => [
        'bigdata' => Erikwang2013\BigData\Integration\Yii2\BigDataComponent::class,
    ],
];

驱动配置优先从 Yii::$app->params['bigdata'] 读取；未设置时使用自动写入的 config/bigdata.php：

$trino = Yii::$app->bigdata->driver('trino');

Yii3

包在 extra.config-plugin 中声明 params 和 di，yiisoft/config 的 Composer 插件会在安装/更新时自动合并包内配置。应用需要允许该插件：

composer config allow-plugins.yiisoft/config true

无需复制文件；应用侧覆盖 config/common/params.php 中的 erikwang2013/bigdata-php 段即可：

// config/common/params.php
return [
    'erikwang2013/bigdata-php' => [
        'default' => 'trino',
        'drivers' => [
            'trino' => ['host' => '127.0.0.1'],
        ],
    ],
];

Manager 已注册到容器，可以注入或直接获取：

final class DashboardController
{
    public function __construct(
        private \Erikwang2013\BigData\Integration\Manager $bigdata,
    ) {
    }
}

或直接从容器获取：

$manager = $container->get(\Erikwang2013\BigData\Integration\Manager::class);
$trino = $manager->driver('trino');

驱动矩阵

19 个平台、21 个驱动键。— 表示没有额外依赖。

驱动键与客户端类的完整命名空间前缀是 Erikwang2013\BigData\。例如 Driver\Trino\TrinoClient 的完整类名是 Erikwang2013\BigData\Driver\Trino\TrinoClient。

Hudi / Paimon 通过 BigData::driver() 使用时必须提供 base_path，可选 storage（local 或 webhdfs）以及 WebHDFS 的 host / port / user：

$table = BigData::driver('hudi', ['base_path' => '/warehouse/orders']);
$latest = $table->latestCommit();

架构设计

调用路径：

1. 应用层：业务代码直接调用 BigData::driver()，或通过框架适配器从容器取得 Integration\Manager。
2. 框架适配层（可选）：Laravel、ThinkPHP、Webman、Hyperf、Yii2、Yii3 适配器读取 default / drivers 配置，把 Manager 绑定到容器；不引入 ORM、查询构造器或额外抽象。
3. Manager / Registry：Manager 负责配置解析和实例缓存；BigData 内部维护 21 个驱动键到工厂闭包的静态映射，未知键和缺失的可选依赖都在这里拦截。
4. 驱动层：每个平台一个目录，包含 XxxConfig、XxxClient（部分驱动还有专用 ResultSet 或异常）。通用 HTTP、结果集、配置读取和异常位于 src/Support/ 与 src/Exception/，驱动只依赖自己的配置和注入的 HTTP / 日志实例。
5. 外部系统：HTTP / JSON（Guzzle 7）、Thrift TCLIService、MySQL 协议（PDO）、CQL、本地文件系统或 WebHDFS。

关键约束：驱动按需创建、按名称缓存；Manager 不会在构造时连接任何外部系统；HTTP 客户端和日志器可以从上层注入，便于统一超时、代理和日志配置。

功能设计

代码分为五层：

• Core：BigData 门面（driver / drivers / available）、Integration\Manager、驱动注册表和可选依赖闸门。核心层只做名称解析、配置合并和工厂调用。
• Support：共享的 Support\Http（Guzzle 7 薄封装）、Support\ResultSet、Support\Config，以及以 BigDataException 为根的异常体系；连接失败与请求失败分别落到 ConnectionException 和 RequestException。Hive、Cassandra、Doris、StarRocks 保留专用异常层级，Hudi/Paimon/Delta Lake 的元数据错误保留 HudiException / PaimonException / DeltaLakeException。
• Driver：按平台隔离的 19 个目录，分为 SQL / OLAP、Hadoop / compute、Schedulers、Lakehouse、NoSQL 五组。驱动之间不共享客户端实例，也不存在跨驱动的统一 SQL 层。
• Optional dependencies：ext-pdo_mysql（仅 Doris/StarRocks SQL）、apache/thrift、mroosz/php-cassandra、aws/aws-sdk-php（仅 S3）。Hive/Cassandra 在创建驱动时检查，PDO 在 SQL 调用时检查，S3 在读取时检查。
• Tests：单元测试使用 mock HTTP、本地 fixture 和 fake server；集成测试独立成组，按需连接真实服务。

这套结构的目标是“统一入口，不统一语义”：配置、结果集和异常命名保持一致，但每个驱动仍按目标系统的协议和错误模型工作。

请求周期

一次典型的驱动调用经过 8 步：

1. 读取配置：应用或框架适配器读取 default 与 drivers；独立脚本直接把配置数组传给 BigData::driver()。
2. 解析驱动名：Manager 使用显式名称或默认名称；直接调用 BigData 时由调用方传入名称。
3. 校验驱动键与可选依赖：注册表检查名称；doris / starrocks 检查 pdo_mysql，hive 检查 apache/thrift，cassandra 检查 mroosz/php-cassandra。
4. 创建配置与客户端：工厂调用 XxxConfig::fromArray()，再构造 XxxClient；Guzzle 客户端和 PSR-3 日志器可以注入。
5. 认证（如需要）：HTTP Basic / Bearer / token、Hive SASL PLAIN 或 LDAP、Doris / StarRocks 的 PDO 登录、Cassandra 的 CQL 认证。
6. 发送传输请求：HTTP/JSON、Thrift TCLIService、PDO MySQL、CQL、本地或 WebHDFS 读取；分页请求可能在这一步发出多次。
7. 解析响应：处理 JSON 与 HTTP 200 下的应用层错误，跟随 nextUri、结果 token 或 offset，解析 Thrift 行批次、PDO 行或 Base64 编码的 HBase 单元格。
8. 返回结果：查询类驱动返回 ResultSet，调度 / 目录类驱动返回驱动特定的数组；Hive 和 Cassandra 的会话由调用方显式 close()。

错误映射：传输失败、超时和连接错误抛出 ConnectionException；HTTP 非 2xx 或应用层错误抛出 RequestException。所有驱动都不自动重试，调用方需要根据幂等性决定是否重试。

生命周期

可选依赖的生命周期是独立的：Hive/Cassandra 在创建驱动时检查类，ext-pdo_mysql 在 Doris/StarRocks 首次执行 SQL 时检查，S3 存储在首次读取时检查；缺失时抛出带安装提示的异常。直接 new 客户端会绕过创建期的检查。

目录结构

bigdata-php/
├── src/
│   ├── BigData.php              # 驱动注册、工厂与可选依赖检查
│   ├── Install.php              # Webman 插件安装器
│   ├── Driver/
│   │   ├── Trino/
│   │   ├── Hadoop/
│   │   ├── Hive/
│   │   ├── Spark/
│   │   ├── Flink/
│   │   ├── Doris/
│   │   ├── StarRocks/
│   │   ├── Kylin/
│   │   ├── Druid/
│   │   ├── Iceberg/
│   │   ├── Hudi/
│   │   ├── Paimon/
│   │   ├── DeltaLake/
│   │   ├── DolphinScheduler/
│   │   ├── Airflow/
│   │   ├── Azkaban/
│   │   ├── Oozie/
│   │   ├── HBase/
│   │   └── Cassandra/
│   ├── Integration/             # 框架适配器与 Manager
│   │   ├── Manager.php
│   │   ├── Laravel/
│   │   ├── ThinkPHP/
│   │   ├── Webman/
│   │   ├── Hyperf/
│   │   ├── Yii2/
│   │   └── Yii3/
│   ├── Support/                 # 共享 HTTP、ResultSet、配置辅助
│   └── Exception/
│       ├── BigDataException.php
│       ├── ConnectionException.php
│       ├── RequestException.php
│       └── DriverUnavailableException.php
├── config/                      # 框架配置样例
├── docs/
│   ├── diagrams/                # 中英文架构、功能、请求周期、生命周期 SVG
│   ├── drivers/                 # 19 个平台的详细文档（en/ 为英文版）
│   ├── frameworks/              # 6 个框架适配文档（en/ 为英文版）
│   ├── pet.svg / pet-expressions/  # 项目宠物及 12 种动态表情
│   └── site/                    # 站点内容源、构建与部署配置
├── scripts/                     # 站点构建 / 检查脚本
├── site/                        # 本地站点构建产物（gitignore，不随发布打包）
├── tests/
│   ├── Driver/                  # 单元测试与 fixture
│   └── Integration/             # 按需运行的集成测试
├── demo/                        # Trino / Flink / Airflow / Cassandra 演示
├── composer.json
├── phpstan.neon
├── phpunit.xml / phpunit-8.0.xml
├── ASSETS-LICENSE.md
├── CHANGELOG.md
├── README.md
└── README_EN.md

测试

composer test              # 单元测试，不依赖真实集群
composer test-integration  # 集成测试，需要可用的外部服务

单元测试使用 mock HTTP 客户端、本地 fixture 和 fake server，覆盖 296 个测试、994 个断言；另有 14 个集成测试。测试套件在 phpunit.xml 中分为 unit 和 integration 两组；默认的 composer test 只运行 unit，不包含 tests/Integration。

集成测试按需运行，例如 Cassandra 需要可访问的实例；demo/ 下提供了 Trino、Flink、Airflow 和 Cassandra 的 Docker Compose 配置，可作为本地验证起点。

边界与限制

• 湖仓只读元数据：Iceberg 读取 REST Catalog 和表元数据；Hudi 读取 .hoodie 时间线；Paimon 读取 schema / snapshot；Delta Sharing 返回 Parquet 文件清单。它们都不读取 Parquet 行数据，也不做谓词下推或查询执行。
• Delta Sharing 不返回行：DeltaSharingClient::query() 返回文件清单和元数据，实际数据需要由调用方按清单读取。
• Hive 认证范围：支持 NONE、NOSASL、SASL PLAIN 和 LDAP（QOP auth）；NONE/PLAIN/LDAP 使用 SASL PLAIN，NOSASL 关闭 SASL；不支持 Kerberos / GSSAPI。binary 传输可通过 tls => true 使用 TLS；HTTP 传输通过 scheme => https。
• Cassandra 可选且可能命名冲突：驱动包装 mroosz/php-cassandra，与 ext-cassandra 共用 Cassandra\ 命名空间，同时加载时可能冲突。
• 不做自动重试：连接、HTTP 和应用层错误直接抛出 ConnectionException / RequestException；重试策略、退避和幂等判断由调用方负责。
• 没有统一 SQL 层或 ORM：驱动只做协议适配，不做 SQL 方言转换、跨源 JOIN、事务编排、连接池或模型映射。
• 可选依赖检查只在 BigData::driver()：直接实例化客户端会跳过检查，缺失的扩展或类会在运行时以 PHP 错误暴露。
• 驱动能力不对称：每个平台只覆盖其公开 API 的一部分；具体方法、配置字段和限制以 docs/drivers/ 下的文档为准。

License

MIT。详见 LICENSE。