首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >PHP 最轻量、结构化 .docx 到 Markdown 转换器 Elephant

PHP 最轻量、结构化 .docx 到 Markdown 转换器 Elephant

作者头像
Tinywan
发布2026-07-10 21:50:56
发布2026-07-10 21:50:56
1270
举报
文章被收录于专栏:开源技术小栈开源技术小栈

elephant-phpEndless Creativity 开发的 PHP 库,核心功能是将 .docx 文档转换为纯 PHP 语义化 HTML 或 Markdown,无需任何外部依赖(LibreOffice、Pandoc、PHPWord 等二进制工具)。

它是 mammoth.js(一个 JS 库)的 PHP 移植版,保留了其核心哲学:提取文档结构而非复制 Word 的视觉格式。使用标准的 PHP 扩展(dom、libxml、mbstring、xmlreader、zip)即可完成转换,适合 RAG、LLM、文档处理、搜索索引等场景。

🚀 主要特点(Features)

  • 纯 PHP 实现:仅依赖标准扩展,无 shell-out、无外部依赖。
  • 结构化输出:生成语义 HTML(支持 h1–h6、表格、脚注、图片等)和 Markdown。
  • 风格映射 DSL(mammoth 兼容):p[style-name='Heading 1'] => h1:freshb => strongtable.Grid => table.fancy 等规则,支持 :fresh :separator('text') 和字符串反斜杠转义(\n、\r 等)。
  • 高级功能
    • 可选值(idPrefix、ignoreEmptyParagraphs、prettyPrint)。
    • 文档转换钩子(transformDocument + Transforms 助手)。
    • 隐藏文本(w:vanish)默认忽略。
    • 复选框表单字段(/ [x] / [ ])。
    • 嵌入式样式映射(in-docx 中声明)。
    • CLI 工具。
  • 安全默认设置:针对未信任输入优化(r:link 图片不加载、javascript: 等链接剥离 、XML 防 XXE/ billion-laughs)。
  • 提取纯文本(extractRawText)用于索引管道。

📦 安装

代码语言:javascript
复制
composer require endless-creativity/elephant-php

PHP 要求:8.2+。

💡 使用示例

HTML 输出

代码语言:javascript
复制
use EndlessCreativity\ElephantPhp\Converter;

$result = (new Converter())->convertToHtml('/path/to/file.docx');

echo $result->value;  // 语义化 HTML
foreach ($result->messages as $msg) {
    fwrite(STDERR, "[{$msg->type->value}] {$msg->message}\n");
}

Markdown 输出

代码语言:javascript
复制
$result = (new Converter())->convertToMarkdown('/path/to/file.docx');
file_put_contents('article.md', $result->value);

自定义样式映射(DSL)

代码语言:javascript
复制
$converter = new Converter(styleMap: [
    "p[style-name='Aside'] => aside.callout",
    "p[style-name='Quote'] => blockquote > p:fresh",
    "r[style-name='Code'] => code",
    "comment-reference => sup",  // 打开注释支持
]);

自定义图片处理器

代码语言:javascript
复制
$handler = new class implements \EndlessCreativity\ElephantPhp\Image\ImageHandler {
    public function attributes(...): array { /* ... */ }
};
$converter = new Converter(imageHandler: $handler);

文档预处理

代码语言:javascript
复制
use EndlessCreativity\ElephantPhp\Document\Transforms;

$converter = new Converter(
    transformDocument: Transforms::run(fn($r) => $r->withBold(true))
);

嵌入式样式映射(读/写)

代码语言:javascript
复制
$bytes = Converter::embedStyleMap('/input.docx', 'p[style-name="Aside"] => p.aside');

🔒 安全默认设置(Security Defaults)

  • r:link 图片不自动加载(防 SSRF/LFI)。
  • javascript: / vbscript: / data: 链接剥离 标签(防 XSS)。
  • XML 解析拒绝 DOCTYPE 并禁用网络实体(防 XXE / billion-laughs)。
本文参与 腾讯云自媒体同步曝光计划,分享自微信公众号。
原始发表:2026-07-08,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 开源技术小栈 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 🚀 主要特点(Features)
  • 📦 安装
  • 💡 使用示例
    • HTML 输出
    • Markdown 输出
    • 自定义样式映射(DSL)
    • 自定义图片处理器
    • 文档预处理
    • 嵌入式样式映射(读/写)
  • 🔒 安全默认设置(Security Defaults)
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档