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 输出

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 输出

$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 = new class implements \EndlessCreativity\ElephantPhp\Image\ImageHandler {
    public function attributes(...): array { /* ... */ }
};
$converter = new Converter(imageHandler: $handler);

文档预处理

use EndlessCreativity\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）。

以上关于PHP 最轻量、结构化 .docx 到 Markdown 转换器 Elephant的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。