nforst/fagus
开发工具为 PHP 和 Laravel 提供无需浏览器的 HTML/CSS 转 PDF,原生 Rust 引擎,支持 PDF/A、PDF/UA 与 ZUGFeRD。
项目介绍
Fagus 是一个 Composer 包,把 HTML 和 CSS 转成 PDF,不需要安装 Chrome、Puppeteer、Node、Docker 镜像或系统库。Composer 会按平台下载一个用 Rust 编写的原生引擎,PHP 通过管道与它通信,进程在文档之间保持运行。主要面向 PHP 和 Laravel 应用里生成发票、报表等打印文档的场景。
引擎按 Chrome 打印的方式排版:支持 flex、grid、Tailwind v4、@page 页边距盒、页眉页脚、页码计数和跨页重复表头。还支持带标签的 PDF/UA-1 无障碍输出、多种 PDF/A 版本,以及 ZUGFeRD/Factur-X 发票附件。README 明确说明项目处于早期开发阶段,CSS 覆盖仍在扩展,1.0 之前小版本可能改动 API。
快速使用
需要 PHP 8.3 或更高版本。用 Composer 安装时,它会询问是否信任 nforst/fagus 的插件;该插件会在每次 install/update 后安装对应平台的 fagus 二进制。
composer require nforst/fagus
最少三行即可把字符串渲染成 PDF:
use Fagus\Fagus;
Fagus::html($html)->save('invoice.pdf');
需要设置资源目录、PDF/A、Factur-X 或查看诊断信息时:
use Fagus\Conformance;
use Fagus\Fagus;
$pdf = Fagus::html($html)
->baseDirectory(__DIR__.'/resources/pdf')
->resource('logo.png', $logo)
->pdfA(Conformance::PdfA3b)
->facturX($invoiceXml)
->render();
$pdf->save('invoice.pdf');
$pdf->diagnostics();
在 Laravel 中会自动注册 Fagus facade、Blade 视图渲染、响应和磁盘支持。运行 php artisan vendor:publish --tag=fagus-config 可发布配置;然后可以用 Fagus::view('invoices.show', ['invoice' => $invoice])->name('invoice.pdf') 直接返回 PDF。首次 PDF 的完整步骤见入门文档,Docker、Alpine、无法访问 GitHub 的服务器以及自备二进制等场景见部署文档。
引擎也能独立作为命令行工具或 Rust 库使用,例如 fagus render invoice.html -o invoice.pdf --font-dir fonts --factur-x invoice.xml。
使用约束
- 有意不执行 JavaScript,图表需要在服务端生成 SVG 或图片后嵌入。
- 字体行为取决于配置:系统字体默认关闭,以保证不同机器输出一致;需要时可以按平台开启。
- 1.0 之前 CSS 覆盖仍在增长,小版本可能改动 API;具体策略见变更日志和稳定性说明。
- 宣称在 Linux x64/arm64、macOS Intel/Apple silicon 和 Windows x64 上自包含运行。
- 许可证为 Apache-2.0 或 MIT,可任选。
HotRepo 点评
该项目在 2026-11-20 的 Rust 新项目榜上有一条记录:约 1.5 小时净增 4 个 Star,累计 106 个 Star。这个记录很小、时间也早,没有进入 GitHub 全部语言日榜,因此不足以判断热度趋势。技术上值得注意的是无浏览器路线:README 自带的基准在 Apple M2 Pro 上测得一页发票首次约 9 ms、后续约 2.3 ms,而常驻 Chrome 为 103/75 ms、mPDF 为 63/25 ms。这些数字来自项目自己的基准环境而非独立测试,但能说明一个支持现代 CSS 的 PHP 发票生成器在走向 1.0 的过程中值得关注。
本文由 AI 根据项目 README 生成,更新于 ,以项目官方文档为准。
相关推荐
- gotenberg/gotenberg一个基于 Docker 的 HTTP API,将 HTML、网址和办公文档转换为 PDF,并支持后续处理。
- rauchg/xeet无需浏览器即可把 X 帖子渲染成像素级精确的 PNG,适用于分享图、预览和自动化测试。
- symfony/symfony用于构建 Web 与控制台应用的 PHP 框架,同时提供一组可复用的 PHP 组件。
- grpc/grpc一个跨语言 RPC 框架,让服务之间像调用本地函数一样通过 HTTP/2 互相通信。
- axios/axios面向浏览器和 Node.js 的 Promise 版 HTTP 客户端,用统一 API 发送请求,并支持拦截器、取消和进度事件。