使用 PHP 绑定调用 Xberg::listRenderers() 管理文档渲染器注册表-平芜编程栈

后端
AI 应用
NLP

【免费下载链接】xberg

Polyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.

项目地址：https://gitcode.com/gh_mirrors/kr/xberg

点击查看免费下载

导读

Xberg::listRenderers()是 xberg 项目 PHP 绑定暴露的插件管理 API，用于列出当前进程中已注册的全部文档渲染器（renderer）名称。渲染器负责把管道内部的文档表示转换为最终输出格式字符串——包括内置的 Markdown、HTML、Djot、DocTags、DOT、DOCX、PDF 与纯文本，以及由用户在运行时注册的自定义格式。读完本文，你将掌握listRenderers()的调用方式、返回数据结构、内置渲染器清单、与clearRenderers()的配合使用，以及它背后由 Rust 核心维护的全局渲染器注册表的工作机制。

文档来源与定位

本主题对应的关联文档为仓库中的自动生成快照：renderers_list.md。它是 alef 多语言绑定生成器产出的 E2E 测试片段，front-matter 声明了id: fixture_php_renderers_list、language: php、target: php，且side_effect: safe（无副作用，可安全重复调用）。该类片段由alef e2e generate生成、alef verify校验新鲜度，因此其中的 PHP 调用代码与当前绑定实现保持同步。

同一类快照还有 renderers_clear.md（清空全部渲染器）与 registry/list_renderers.md（注册表类别下的同功能变体），说明listRenderers同时被归类为插件 API 与注册表管理 API 两类测试主题。

一、核心用法：列出所有已注册渲染器

关联文档给出的完整 PHP 代码段如下：

<?php declare(strict_types=1); require_once __DIR__ . '/vendor/autoload.php'; use Xberg\Xberg; $result = Xberg::listRenderers(); var_dump($result);

关键点逐一说明：

declare(strict_types=1)：PHP 8.2+ 严格类型模式，保证绑定调用传参/返回类型校验严格；
require_once __DIR__ . '/vendor/autoload.php'：加载 Composer 自动加载器。PHP 包通过composer require xberg-io/xberg安装（见 packages/php/README.md）；
Xberg::listRenderers()：静态调用，对应 Rust 端list_renderers()函数。它无参数、无副作用，返回当前全局注册表中全部渲染器名称的字符串数组；
var_dump($result)：输出数组内容与类型，适合在脚本中快速确认注册表状态。

返回值语义

Rust 端实现位于 crates/xberg/src/plugins/renderer.rs：

pub fn list_renderers() -> Result<Vec<String>> { use crate::plugins::registry::get_renderer_registry(); let registry = get_renderer_registry(); let registry = registry.read(); Ok(registry.list()) }

函数读取全局注册表的只读锁并返回Vec<String>——即每个渲染器的格式名（format name）。在 PHP 中，这对应list<string>类型的结果，可直接用foreach遍历或in_array()判断某个格式是否可用：

foreach ($result as $name) { echo "renderer: {$name}\n"; }

二、内置渲染器：注册表默认装载的八种格式

listRenderers()首次调用时，返回的列表并非空数组。全局注册表在构造时会装载一批内置渲染器（见 crates/xberg/src/plugins/registry/renderer.rs）：

渲染器名称	输出格式	说明
`markdown`	GFM Markdown	基于 comrak 渲染
`html`	HTML5	基于 comrak 渲染
`djot`	Djot 标记语言	Djot 语法输出
`doctags`	Docling DocTags	表格输出为 OTSL（对象树序列化语言）
`dot`	Graphviz DOT	从矢量来源恢复的图表
`docx`	Office Open XML	base64 编码，需`office`特性（feature）编译
`pdf`	PDF	base64 编码，需`pdf`特性编译
`plain`	纯文本	无任何格式

其中docx与pdf渲染器受 Cargo feature 门控：只有启用office/pdf特性构建的二进制才会注册这两个名称。因此listRenderers()返回的具体集合取决于运行环境构建配置，这一点在跨环境比对输出时应特别注意。

上述默认集也体现在 registry 文档注释与单元测试中，例如 crates/xberg/src/plugins/registry/renderer.rs 明确注释内置渲染器为"markdown", "html", "djot", "doctags", "dot", "docx", "pdf", "plain"。

三、结合 clearRenderers() 的注册表管理闭环

listRenderers()通常与写入型 API 搭配使用，形成"查看-修改-复查"的管理闭环。关联的姊妹快照 renderers_clear.md 演示了清空操作：

<?php declare(strict_types=1); require_once __DIR__ . '/vendor/autoload.php'; use Xberg\Xberg; Xberg::clearRenderers();

典型排查流程：

调用Xberg::listRenderers()记录当前注册表快照；
注册自定义渲染器（Xberg::registerRenderer(...)）或清空注册表（Xberg::clearRenderers()）；
再次调用Xberg::listRenderers()验证变更生效。

clearRenderers()在 Rust 端对应 crates/xberg/src/plugins/renderer.rs 的clear_renderers()，会移除包括内置渲染器在内的全部条目。清空后注册表为空——此时若某次渲染请求按名称查找渲染器，将由自愈机制ensure_renderers_initialized()重新装载内置渲染器（见 crates/xberg/src/plugins/renderer.rs），确保Custom输出格式派发路径不会因注册表被清空而中断。该自愈过程非破坏性：用户注册的渲染器会被保留。

四、底层原理：全局渲染器注册表

listRenderers()的数据来源是 crate 级的全局单例注册表，定义于 crates/xberg/src/plugins/registry/renderer.rs。其核心结构为：

pub struct RendererRegistry { renderers: AHashMap<String, RegisteredRenderer>, }

键为格式名：即Plugin::name()的返回值，也是listRenderers()返回列表中的每个元素；
值为 RegisteredRenderer：区分内部（internal，即原生 Rust 渲染器）与公开（public，即跨语言桥接注册的渲染器）两种来源；
线程安全：通过parking_lot::RwLock保护，可被多线程并发读写；list_renderers()仅取读锁，因此并发安全且无副作用。

渲染器本身是Plugin特性的子类型。公开的Renderer特性定义了绑定安全的入口render_result(&ExtractedDocument) -> Result<String>，其默认实现直接返回result.content原样文本（见 crates/xberg/src/plugins/renderer.rs）。这意味着即使是最简单的自定义渲染器，不覆盖render_result也能通过注册表列出，只是行为退化为"透传已渲染文本"。

从源码结构看注册/注销对称性

与listRenderers()配套的还有：

register_renderer(Arc<dyn Renderer>) -> Result<()>——注册渲染器，名称冲突时以新替旧，并对名称做合法性校验（crates/xberg/src/plugins/renderer.rs）；
unregister_renderer(name: &str) -> Result<()>——按格式名注销（同文件 L112-L118）；
clear_renderers() -> Result<()>——清空全部（同文件 L141-L148）。

这些函数均通过get_renderer_registry()获取全局注册表，构成一个对称、可审计的插件生命周期：list只读、register/unregister精确变更、clear整体重置。

五、测试与 E2E 契约：如何验证该 API 的行为

单元测试证据

Rust 核心的单元测试直接验证了list_renderers()与注册/注销/清空的联动（crates/xberg/src/plugins/renderer.rs）：

register_list_unregister_roundtrip：注册test-fmt-a后，list_renderers()结果必须包含该名称；注销后必须不再包含；
register_list_clear_list_roundtrip：注册test-fmt-b后list_renderers()包含它；调用clear_renderers()后列表为空。

这两组用例精确刻画了listRenderers()的语义：它是注册表当前状态的忠实镜像。

E2E fixture 契约

PHP 侧的调用由 JSON fixture 驱动生成：renderers_list.json 声明了：

{ "id": "renderers_list", "category": "renderer_management", "call": "list_renderers", "assertions": [{ "type": "not_error" }] }

即该用例的核心断言是"调用不报错"，验证 PHP 绑定到 Rust 核心的调用链（Xberg::listRenderers()→ alef trait-bridge →list_renderers()）可用。fixture 体系说明见 fixtures/plugin_api/README.md，其中simple_list模式描述的正是这种"无需 setup、返回字符串列表"的测试形态。所有 E2E 测试均由 fixture 生成，不允许手写（见 README 的 Notes 章节），以保证 15 种语言绑定的 API 行为完全一致。

六、实战建议

排查渲染问题优先列清单：当Custom输出格式渲染异常时，先Xberg::listRenderers()确认期望的格式名是否在注册表中，再判断是 feature 未启用还是注册表被清空；
注意 feature 门控差异：docx/pdf是否出现在列表中取决于构建时是否启用office/pdf特性，不要对这两项做硬性假设；
把 clear 视作可自愈操作：clearRenderers()清空内置渲染器后，下一次渲染会触发ensure_renderers_initialized()自愈重装，无需手动重新注册内置项；
在脚本中做存在性检查：注册自定义渲染器前，可先listRenderers()判断格式名是否已被占用（register同名校名会覆盖旧渲染器）。