symboi/silverstripe-pdfrendition

一个模块,利用Flying Saucer XHTML渲染器项目,从XHTML页面创建PDF。

安装次数: 4,818

依赖项: 0

建议者: 0

安全性: 0

星标: 17

关注者: 3

分支: 10

开放性问题: 6

类型:silverstripe-vendormodule

2.1.1 2021-02-24 01:00 UTC

This package is auto-updated.

Last update: 2024-08-30 07:46:55 UTC


README

维护者联系方式

要求

  • SilverStripe 4.12+ || 5+
  • Tidy(最好是内置的PHP tidy模块,否则是命令行二进制文件)
  • Java 1.8(这是已测试的最新版本)
    • 重要:早于1.7的版本会导致PDF无法加载特定于Cloudflare的资产(如图像和CSS)
    • 重要:无论您最终使用哪个版本,在上线之前,请确保生产服务器上的PDF输出是正确的(请参阅以下已知问题部分)

文档

此模块允许用户通过利用HTML和CSS3定义打印页面布局,轻松创建复杂的内容PDF版本。它提供了一个简单的扩展,用于自动生成页面PDF版本,并为开发者提供了一个生成更特定PDF版本的API。

安装说明

composer require symbiote/silverstripe-pdfrendition

使用概述

  • Symbiote\PdfRendition\Extension\PdfControllerExtension作为扩展添加到PageController
  • 在您的模板中添加$PdfLink以插入指向页面PDF版本的链接
  • 要自定义PDF布局,在您的主题目录中创建一个'pdfrendition.css'文件,使用您首选的方法(@import、requirements等)将其链接,并使用@print媒体查询添加特定于PDF的样式。请参阅github wiki以了解一些常见PDF相关操作的示例。

已知问题/故障排除

  • 在不具备有效证书的情况下使用HTTPS可能会导致PDF无法正确渲染。
  • Cloudflare可能会导致PDF无法正确渲染。
    • 这可能是由于Java尝试引用资产(图像和CSS),并被视为“不良浏览器”。
      • 要解决这个问题,需要在CloudflarePage Rules中为这些特定资产(或通用的/*通配符规则)添加规则,并将Browser Integrity Check设置为关闭
    • 这也可能是因为Java的版本(请参阅上方)。
    • 可以通过在本地拦截渲染过程并保留在渲染之前生成的文件来测试PDF输出。
    • 使用此方法,将资产URL替换为您想要测试和确认的URL(例如生产环境)。
      • Java Flying Saucer工具将通过源中包含的链接检索资产和外部来源。请确保这些链接是完整的,并且可以从生产服务器中检索(例如,出站防火墙限制或本地化的DNS/主机定义可能会导致问题)。
    • 使用此/tmp/xhtml,在生产服务器上运行以下命令应该会生成一个正确渲染的PDF。
    • 如果不这样做,则Cloudflare和/或Java可能是问题所在。

java -classpath '{project}/pdfrendition/thirdparty/xhtmlrenderer/flying-saucer-core-9.0.7.jar:{project}/pdfrendition/thirdparty/xhtmlrenderer/flying-saucer-pdf-9.0.7.jar:{project}/pdfrendition/thirdparty/xhtmlrenderer/itext-4.2.1.jar' org.xhtmlrenderer.simple.PDFRenderer '/tmp/xhtml' '/tmp/output.pdf'

  • 确保您不要在@media print内部定义@font-face。

有时页面无法正确渲染,PDF渲染过程失败时,会向浏览器返回一些垃圾信息。通常,这是由发送给渲染器的XML格式错误造成的;因此,所有内容首先通过HTML Tidy进行过滤,但在一些罕见情况下,这仍然无法正确转换原始内容。

在这种情况下,错误将通过错误日志文件发送;它会指示创建的临时文件,因此您应该首先检查这些文件以查找XML错误。如果这不起作用,您还可以尝试使用命令行tidy和PDF渲染的命令行手动执行转换,以查看是否有更详细的错误可供调试问题。