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

elephant-php 是 Endless 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:fresh、b => strong、table.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）用于索引管道。

📦 安装

composer require endless-creativity/elephant-php

PHP 要求：8.2+。

💡 使用示例

HTML 输出

useEndlessCreativity\ElephantPhp\Converter;$result = (new Converter())->convertToHtml('/path/to/file.docx');echo $result->value;  // 语义化 HTMLforeach ($result->messages as $msg) {    fwrite(STDERR, "[{$msg->type->value}] {$msg->message}\n");}

Markdown 输出

$result = (new Converter())->convertToMarkdown('/path/to/file.docx');file_put_contents('article.md', $result->value);

自定义样式映射（DSL）

$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",  // 打开注释支持]);

自定义图片处理器

$handler = newclassimplements \EndlessCreativity\ElephantPhp\Image\ImageHandler{publicfunctionattributes(...): array{ /* ... */ }};$converter = new Converter(imageHandler: $handler);

文档预处理

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

嵌入式样式映射（读/写）

$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）。