Download the PHP package goletter/hyperf-docs without Composer

Docs

Hyperf 文档平台扩展包，支持多平台：

• Google：OAuth、Sheets、Drive（gid 定位、追加、按内容查找、受保护列 / 勾选框）
• 腾讯文档：OAuth、在线表格、文件夹、分享权限
• 飞书：OAuth（user_access_token）、电子表格、云空间文件夹、链接分享

安装

本地 path 开发（推荐，可自动加载 ConfigProvider）

Hyperf 通过 Composer::getMergedExtra('hyperf')['config'] 收集各已安装包的 extra.hyperf.config。
若只在根项目 autoload.psr-4 映射源码目录，包不会进入 vendor/composer/installed.json，ConfigProvider 不会自动加载。

请用 path 仓库以 Composer 包方式引入：

然后执行：

成功后会出现 vendor/goletter/hyperf-docs（一般为软链），ConfigProvider 中的 dependencies / annotations.scan.paths / publish 会自动合并进框架，无需再在 config/autoload/dependencies.php 手动绑定。

不要同时保留根项目 autoload.psr-4 里的 Goletter\\Docs\\ 映射，以免与 path 包重复定义。

配置

发布配置：

从数据库读取平台凭证（使用说明）

适用：OAuth 应用凭证（client_id / secret / redirect_uri 等）按环境或租户存在库里，不想写死在 .env。
不存：用户的 access_token / refresh_token（仍由业务表保存，调用时传入）。

1. 依赖与开关

重新发布或手动合并 config/autoload/docs.php 中的 config_source / database 段。

2. 建表并写入配置

推荐：平铺列（无 JSON）：

也兼容旧的 JSON 列 config：有值时优先用 JSON；没有该列或为空则读 attributes 平铺字段。空字符串不会覆盖 .env 兜底。

飞书可用 app_id / app_secret（也兼容 client_id / client_secret），按需把列名加进 docs.database.attributes。

合并规则：库字段覆盖文件；库里没有的 key 仍用 docs.platforms.*（.env）兜底。

3. 业务调用（与原来相同）

4. 多租户（可选）

在进入业务前设置协程上下文，同一请求内后续读写都会带上该 tenant_id 查库：

未设置 tenant_id 时查 tenant_id IS NULL（或空字符串）的全局行。

5. 自定义配置源（可选）

实现 Goletter\Docs\Contract\PlatformConfigRepositoryInterface，在项目 dependencies 里覆盖绑定即可（不必改本包）。

环境变量：

Google：access_token 短期有效，请保存 refresh_token 并在过期后刷新。
腾讯文档需先在 开放合作平台 创建应用并完成审核；OpenAPI 除 Access-Token 外必须带 Open-Id（换 token 回包中的 user_id）。表格接口通常需要 scope.sheet / scope.sheet.readonly。
飞书需在 开放平台 创建应用，开通电子表格 / 云文档权限，并配置重定向 URL。授权 scope 须含 offline_access 才能拿到 refresh_token（每次刷新都会换新的 refresh_token，旧的立即失效）。token 只需 access_token，无需 open_id。

使用

三个平台都已定义，通过工厂模式创建，可同时配置、按需选用。

传入配置创建实例

业务表里已有 OAuth 应用凭证时，不必依赖全局 docs.platforms / 库表，直接传配置拿独立实例（缺的 key 仍回落文件默认）：

make($name, $config) 仅支持内置 google / tencent / feishu；每次调用新建对象，不污染全局配置与容器单例。用户 access_token 仍在调用时传入。

请求耗时日志

默认关闭。开启后，Google / 腾讯 / 飞书 Client 每次出口请求会写一条耗时日志（不含 token / secret）。

config/autoload/logger.php 增加独立 channel（示例）：

并合并 docs.logging 到已发布的 config/autoload/docs.php（或重新 vendor:publish）。需安装 hyperf/logger。

日志示例：

扩展自定义平台：

统一 createSpreadsheet 返回值：

Google OAuth / Sheets

Range / gid

读取

按内容查找指定行

写入（受保护列 / 勾选框）

编辑指定行

删除指定行

追加到表格末尾

含 null 时会先算下一空行，再只写有值的列（避开受保护列）。勾选列请传布尔 true / false，不要用 ''。

插在表头下方（旧数据下推）

按条件 upsert（有则改，无则插到表头下）

命中已有行时，只有数据有变化才会写入；内容完全一致则跳过，不进入 updated。null 单元格表示跳过该格（不参与比较、也不覆盖）。

左右分块表（只动某一区块）

$values 只含该区块列（首元素=区块首列）。默认行为与整表 insertAfterHeader / upsertRows 一致：插在第 1 行表头下面、本区块旧数据下推、可批量；有则改、无则插表头下。

你这种「两行表头 + 合计」的表，数据从第 4 行起，显式传 dataStartRow: 4：

prepend 时格式是否跟着下移：

• Google：用「插入单元格并下移」，格式随数据下移，新行沿用下一行的格式。
• 腾讯文档：开放接口没有插入行/单元格，也不能设置对齐，只能读出后整块写回，格式留在原单元格。需先把区块数据区（如 A4:E1000）统一设好对齐等格式，否则下移到空白格的数据会是默认样式。

其它

也可直接注入底层 GoogleAuth / GoogleSheets（不经过工厂），参数为原始 accessToken 字符串。

腾讯文档 OAuth / 表格

权限变更或接口报 Request Scope Invalid 时：在开放平台开通表格相关权限 → 用户重新授权换新 token。

飞书 OAuth / 电子表格

飞书 range 最终会解析成 {sheetId}!A1:B2：

列区块 insertBlock / upsertBlock：飞书 insert_dimension 是整行插入，区块场景采用「读区块 + 合并写回」，只改指定列，不影响左右其它块（与腾讯类似）。表头下整表插入走原生 insert_dimension_range。

能力对照