cooltronicpl/document-helpers

使用Craft CMS的PDF生成器革命性地改变您的PDF创建流程。使用可定制的模板和各种选项轻松创建和管理PDF。

维护者

详细信息

github.com/cooltronicpl/Craft-document-helpers

源代码

问题

文档

安装次数: 3,512

依赖项: 0

建议者: 0

安全: 0

星标: 12

关注者: 1

分支: 6

公开问题: 1

类型:craft-plugin

3.0.0 2024-09-25 18:52 UTC

Requires

proprietary 496d2067c4ff8b5d5473af189fcab63ceb197684

twigthumbnailmpdfqrcodewatermarkpurifybookmarkscrapeTOCpdf-apdf-x

This package is auto-updated.

Last update: 2024-09-25 19:15:29 UTC

README

由CoolTRONIC.pl sp. z o.o.和Pawel Potacki开发。此插件允许您使用mPDF库从Twig模板生成PDF文件。您可以使用各种选项自定义PDF输出，并将其保存为文件、资产或字符串。您还可以使用URL或HTML代码块作为模板。

Icon Icon

内容

安装

您可以从Craft插件商店或通过Composer安装PDF生成器插件。

转到项目控制面板中的Craft CMS插件商店，搜索"PDF Generator"。然后点击其模态窗口中的"安装"按钮。

打开您的终端并转到您的Craft项目

# go to project directory
cd /path/to/project
# Then tell Composer to require the plugin
composer require cooltronicpl/document-helpers
# tell Craft to install and enable the plugin
./craft plugin/install document-helpers
./craft plugin/enable document-helpers

使用

pdf方法参数

pdf方法从Twig模板生成PDF文件，并返回文件的URL。此方法接受参数数组

  • template - 这是PDF模板文件的位置，应在/templates目录中。您还可以从1.3.2或0.4.2传递URL或HTML代码块。

  • destination - 这表示PDF文件将生成的地方。可以是四个选项之一：file、inline、download或string。要下载多个文件，请参阅README.md文件中提供的JavaScript示例。

  • filename - 这是生成的PDF文件名。如果提供为null，则将生成随机文件名。

  • entry - 这代表将要输入到模板中以生成PDF的数据。这些数据包含在 Entry 类型中。如果提供为 null，将创建一个空的Entry以传递函数。

  • pdfOptions - 此参数允许您自定义PDF的生成。可用的选项在覆盖默认选项的章节中描述。

方法返回包含文件名的字符串，用于锚点，或者字符串内容，用于发送作为附件的PDF文件。

{{craft.documentHelper.pdf("template.twig", "file", "document.pdf", entry, pdfOptions)}}

pdf 方法的示例

<a href="{{alias('@web')}}/
{{craft.documentHelper.pdf("_pdf/document.twig", "file",  'pdf/' ~ entry.id ~ '.pdf', entry, pdfOptions)}}"
download>
</a>

pdfAsset方法参数

pdfAsset 方法从Twig模板生成PDF文件，将其保存为资产，并返回Asset模型。此方法接受一组参数

  • template - 这是PDF模板文件的存储位置，应位于 /templates 目录中。您还可以现在传递URL或来自1.3.2或0.4.2的HTML代码块。

  • filename - 这是临时或最终生成的PDF文件的名称。如果提供为 null，将生成一个随机文件名。

  • entry - 这代表将要输入到模板中以生成PDF的数据。这些数据包含在 Entry 类型中。如果提供为 null，将创建一个空的Entry以传递函数。

  • pdfOptions - 此参数允许您自定义PDF的生成。可用的选项在覆盖默认选项的章节中描述。

  • volumeHandle - 此参数是必需的，指定要添加为Craft CMS资产的PDF的Volume Handle。Volume Handle需要一个 Base URL，例如Craft CMS文件系统、资产设置的 @web\pdffiles 用于测试。

pdfAsset 方法的示例

{% set asset = craft.documentHelper.pdfAsset('_pdf/document.twig', alias('@root')~'/example.pdf', entry, pdfOptions, 'pdffiles') %}
{% if asset %}
    <a href="{{asset.url()}}?v={{asset.dateModified|date('U')}}">Download your PDF</a>
{% else %}
    The file was not generated.
{% endif %}

在不保存到/web文件夹的情况下安全地显示PDF文档

您可以在不将其保存到 /web 文件夹的情况下安全地在浏览器中显示PDF文档，如下所示

                        {% set pdfOptions = {
                        date: entry.dateUpdated|date('U'),
                        header: "_pdf/header.twig",
                        footer: "_pdf/footer.twig"
                        } %}
                {% header "Content-Type: application/pdf" %}
{{craft.documentHelper.pdf('_pdf/document.twig', 'inline', '../book_example'  ~ '.pdf', entry, pdfOptions)}}

模板中的变量

在PDF Twig模板中，您可以在生成的Twig模板数组中访问传递的 entry

{{entry.VAR}}

当前条目的标题可以通过以下方式访问

{{title}}

如何通过代码块和URL使用自定义模板

您可以使用URL或HTML代码块作为PDF文件的模板。为此，将URL或HTML代码块作为 template 参数传递。

当遇到URL问题时，您可以设置 encoding，建议设置为 UTF-8。使用URL作为模板的示例

{% set pdfOptions = {
        
    }
%} 
<a href="{{alias('@web')}}{{craft.documentHelper.pdf('https://cooltronic.pl/', 'file', 'pdf/exampleURL.pdf'  , entry, pdfOptions)}}">URL Example</a>

在插件设置中安装自定义URL Purifier (HTMLPurifier) 包后，您可以解决抓取外部网站的问题并启用 URLPurify 选项。当遇到问题时，请尝试在 @root 路径中安装此包

# Craft CMS 4, 5.0.0.alpha
composer require ezyang/htmlpurifier:^4.17 
# Craft CMS 3
composer require ezyang/htmlpurifier:^4.13

代码块的示例

{% set pdfOptions = {

    }
%}    
{% set html %}
    <h1>This is a basic example</h1>
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod.</p>
    <br>
    <p>HTML Contents</p>
{% endset %}

<a href="{{alias('@web')}}{{craft.documentHelper.pdf(html, 'file', 'pdf/exampleHTML.pdf'  , entry, pdfOptions)}}">HTML PDF</a>

如何通过代码块使用自定义变量

您可以使用 pdfOptions 数组中的 custom 或 qrimg 选项向PDF模板传递自定义变量。custom 选项允许传递任何变量，而 qrimg 选项允许从 qrdata 变量传递QR码图像。

使用自定义变量的示例

{% set pdfOptions = {
    qrdata: "https://cooltronic.pl"
    custom: entry.var
    }
%}
{% set pdf_content %}
    <h1>This is a basic example</h1>
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod.</p>
    <br>
    {% verbatim %}
    <p>QR Code:</p>
    <img src="{{qrimg}}" alt="QR Code"/>
    {{custom}}
    {% endverbatim %}
{% endset %}
<a href="{{alias('@web')}}{{craft.documentHelper.pdf(pdf_content, 'file', 'pdf/html.pdf', entry , pdfOptions)}}">HTML QR Code & Custom PDF</a>

覆盖默认选项

您可以使用如上所示的 pdfOptions 覆盖默认选项。以下是可用的选项

  • date（默认：null）- 如果您提供一个早于文件创建日期的日期（以时间戳格式），则将覆盖现有文件。否则，文件将不会修改。
  • header（默认：null）- 可选的模板文件位置，用于页眉，应位于 /templates 目录中。您也可以使用URL或HTML代码块作为模板。例如，header: "_pdf/header.html"，footer: "https://example.com/someheader" 或 header: "<h1>My Header</h1>"。
  • footer（默认：null）- 可选的模板文件位置，用于页脚，应位于 /templates 目录中。您也可以使用URL或HTML代码块作为模板。例如，footer: "_pdf/footer.twig"，footer: "https://example.com/somefooter" 或 footer: "<p>My Footer</p>"。
  • margin_top（默认：30）- 顶部边距以毫米为单位。
  • margin_bottom (默认: 30) - 底部边距以毫米为单位。
  • margin_left (默认: 15) - 左边距以毫米为单位。
  • margin_right (默认: 15) - 右边距以毫米为单位。
  • mirrorMargins (默认: 0) - 是否为奇偶页使用不同的边距。设置为 1 以启用此功能。
  • pageNumbers (默认: false) - 是否在页脚中添加页码。设置为 true 以启用此功能。
  • title (默认: null) - 这将替换生成的 PDF 文档的默认标题。
  • custom (默认: null) - 这允许您添加自定义变量或变量。
  • password (默认: null) - 这可以用于为 PDF 添加密码保护。密码应作为字符串提供。
  • no_auto_page_break (默认: null) - 这将禁用自动系统分页。如果您需要手动添加分页，这可能很有用。例如，您可以使用 <pagebreak> 为具有多页分页的文档添加自定义页。这可能在某些情况下解决分页问题。
  • disableCopyright (默认: null) - 此选项需要 Plus 计划，并且可以用于禁用不可见的版权标记（以删除不可见的水印）。
  • author (默认: null) - 这将设置作者元数据。应作为字符串提供。
  • keywords (默认: null) - 这将设置关键字元数据。应以以下格式提供字符串：“keyword1, longer keyword2, keyword3”。
  • fonts (默认: null)
    • fontdata (默认: null) 和 fontDir (默认: null) - 这些允许您设置上面描述的自定义字体。
  • tempDir (默认: @runtime/temp/pdfgenerator) - 这将设置用于生成 PDF 的临时目录的路径。我们已经在服务器上的主 /tmp 目录上成功进行了测试。这可能在生成多个 PDF 时提高性能。
  • landscape (默认: null) - 如果设置此选项，PDF 将以横幅模式生成。
  • portrait (默认: null) - 如果设置此选项，PDF 将以竖幅模式生成。
  • format (默认: A4) - 此选项设置 PDF 的纸张大小。默认为 "A4"，但您可以设置与 MPDF 兼容的其他大小。其他流行的格式包括
    • A3
    • A4 (默认)
    • A5
    • Letter (8,5 x 11 in)
    • Legal (8,5 x 14 in)
    • Executive (7,25 x 10,5 in)
    • B4
    • B5
  • generateMode (默认: null) - 此选项需要 Plus 计划，并可设置为字符串
    • pdfa 用于 PDF-A
    • pdfx 用于 PDF-X
    • pdfaauto 用于具有常见校正的 PDF-A
    • pdfxauto 用于具有常见校正的 PDF-X
  • colorspace (默认: null) - 此选项可以设置为整数
    • 1 - 只允许 GRAYSCALE [转换 CMYK/RGB→gray]
    • 2 - 允许 RGB / SPOT COLOR / Grayscale [转换 CMYK→RGB]
    • 3 - 允许 CMYK / SPOT COLOR / Grayscale [转换 RGB→CMYK]
    • 0 - 或任何其他值：不对使用的色彩空间施加限制
  • startPage (默认: null) - 要生成的 PDF 的第一页。您可以使用此选项从 PDF 的开头删除不必要的页。例如，startPage: 2 将跳过 PDF 的第一页。
  • endPage (默认: null) - 要生成的 PDF 的最后一页。您可以使用此选项从 PDF 的末尾删除不必要的页。例如，endPage: 10 将生成仅包含 10 页的 PDF。
  • watermarkImage (默认: null) - 此选项使用提供的路径指定的图像文件创建水印。
  • watermarkText (默认: null) - 此选项使用提供的文本创建水印。
  • autoToC (默认：null) - 此选项自动使用文档中的 H1-H6 标签生成目录。
  • autoBookmarks (默认：null) - 此选项自动使用文档中的 H1-H6 标签生成书签。
  • assetTitle (默认：null) - 此选项允许您在使用 pdfAsset 方法时，为 Craft CMS 系统中的资产设置自定义标题。
  • assetFilename (默认：null) - 此选项允许您在使用 pdfAsset 方法时，更改 Craft CMS 资产中文件的目标文件名。
  • assetDelete (默认：null) - 此选项启用删除在 @root 路径内部生成的文件。请注意，此操作不可逆，并且可能消耗更多资源。这是因为在使用 pdfAsset 方法时，资产会在每次加载时更新，并且生成 PDF。
  • assetSiteId (默认：null) - 此选项允许您将自定义的 siteId 分配给 pdfAsset 方法的资产。应将 siteId 作为数字传递，代表应属于生成资产的网站的 ID。
  • assetThumb (默认：null) - 此选项使用 pdfAsset 方法生成 Craft CMS 图像资产的缩略图（需要 ImageMagick）。它可以在 Twig 模板中通过 asset.assetThumb 访问。
    • assetThumbVolumeHandle (默认：null): 此参数是可选的，并定义了缩略图的 Volume Handle。如果未设置，则回退到 PDF Volume Handle。Volume Handle 需要 Base URL，例如 Craft CMS 文件系统、资产设置的测试中的 @web\pdffiles。
  • dumbThumb (默认：null) - 此选项使用 pdf 方法生成基本的缩略图图像（不包含资产）（需要 ImageMagick）。
    • dumbThumbFilename (默认：null) - 生成的图像的自定义文件名，将添加 thumbType 扩展名到文件名。
    • dumbThumbDir (默认：null) - 生成的图像的自定义保存目录，必须存在。

两者 assetThumb 和 dumbThumb 都支持以下可选自定义

  • thumbType - 此参数允许您选择缩略图的格式。选项包括 jpg、gif、webp、avif 和 png。默认格式是 jpg。
  • thumbWidth - 此参数指定缩略图的宽度（以像素为单位）。默认宽度是 210。
  • thumbHeight - 此参数指定缩略图的高度（以像素为单位）。默认高度是 297。
  • thumbPage - 此参数指定生成缩略图的页面。默认为第一页，从 0 开始编号。
  • thumbQuality - 生成的缩略图图像的质量（从最低的）0 到 100（最高的）。
  • thumbBgColor - 此参数指定缩略图的背景颜色。选项包括 black、rgb(33,66,99) 和 #123456。默认颜色是 white。
  • thumbTrim - 当设置为 true 时，此参数修剪页面并将内容居中。默认值是 false。
  • thumbTrimFrameColor - 此参数更改修剪框的颜色。颜色可以是 black 或 RGB 格式（例如，rgb(12,1,2)）或 HEX 格式（例如，#662266）。
  • thumbBestfit - 此布尔值确定是否在给定的尺寸内拟合图像。如果 true，则图像将被缩放以适应给定的尺寸。如果 false，则图像将被拉伸或裁剪以填充给定的尺寸。

高级选项

  • encoding（默认：null）- 这可以设置支持的编码，如iconv()函数支持的UTF-8。更多详情请参考这里。
  • disableCompression（默认：false）- 将此选项设置为true可禁用生成的PDF文件的自动压缩。这可能会增加文件大小，但也会提高质量。
  • qrdata（默认：null）- 此选项允许您从您提供的数据生成QR码图片。图片将通过{{qrimg}}变量在Twig模板中可用。需要从插件设置中安装可选包。
  • URLPurify（默认：null）- 是否启用外部库来清理template参数中提供的URL的HTML。设置为true以启用此功能。
  • URLTwigRender（默认：null）- 是否在解析自定义URL时渲染Twig变量。这允许使用像{{custom}}或作为{{qrimg}}的QR码等属性。设置为true以启用此功能。
  • URLMode（默认：null）- 此选项可以设置为curl，通过CURL获取URL，而不是通过file_get_contents()。
  • convertImgToCMYK（默认：null）- 将此选项设置为true，以在PDF-X模式下将所有图片转换为CMYK，需要安装可选包simplehtmldom/simplehtmldom。此选项需要Plus计划并需要ImageMagick。
  • log（默认：null）- 此选项将调试mPDF的输出打印到指定的文件中。例如，log: @alias(root) ~ '/pdflog.txt'。
  • protection（默认：null）- 此选项需要Plus计划，并可用于限制用户在PDF文件上可以执行的操作。您可以通过传递包含以下值的字符串数组或JSON字符串来启用Plus计划的保护模式（以使PDF与ISO、BSI和DIN标准兼容）
    • copy - 复制文本和图形。
    • print - 低分辨率打印。
    • modify - 修改文档内容。
    • annot-forms - 添加注释和表单字段。
    • fill-forms - 填写现有的表单字段。
    • extract - 提取文本和图形。
    • assemble - 合并页面和文档。
    • print-highres - 高分辨率打印。
    • no-user-password - 无密码打开文档。

例如，protection: ["copy", "no-user-password"]或protection: '["copy", "no-user-password"]'将允许用户复制文本和图形，并无需密码打开文档，但将禁用除复制文本之外的所有其他操作。

您还可以通过在插件设置中检查选项并在pdfOptions参数中覆盖它们来全局选择这些选项。

自定义字体

这是一个如何使用自定义字体（特别是Roboto-Regular.ttf和Roboto-Italic.ttf）的示例，这些字体应放置在配置文件夹中

fontdata: { 'roboto' : {
            'R' : 'Roboto-Regular.ttf',
            'I' : 'Roboto-Italic.ttf'
        }},
        fontDir: "{{craft.app.path.configPath}}/",

在PDF生成器使用的MPDF更新后，我们已解决传递路径的问题。现在，您必须在服务器上提供到配置目录的绝对路径。或者，您可以传递主文件夹。例如，在ISP Config 3.2主机上，您可以使用：fontDir: /var/www/clients/client0/web21/private/config/。

如果您正在运行单个站点，它应该是到/config文件夹的绝对路径，例如fontDir: /path_to/config/。

对于Windows主机上的XAMPP，已确认格式为fontDir: file:///C:/xampp/htdocs/craft4/config/。

返回值

  • 如果目标为inline或string，插件返回一个字符串。
  • 如果目标为download或file，它返回/web文件夹中的文件名。
  • 如果在PDF生成过程中发生错误，方法将返回false。

循环示例

您可以在循环中生成多个PDF文件。例如，您可以针对每个部分中的条目生成一个PDF文件。

{% for item in craft.entries.section('xxx').orderBy('title asc').all() %}
    {% set pdfOptions = {
        date: entry.dateUpdated|date('U'),
    } %}
    <a href="
    {{alias('@web')}}/
    {{craft.documentHelper.pdf("_pdf/document.twig", "file",  'pdf/' ~ item.id ~ '.pdf' ,item, pdfOptions)}}
    " download>
        DOWNLOAD {{item.title}}
    </a>
{% endfor %}

Twig模板示例

这是一个示例，展示如何使用Twig模板生成PDF文档。

<!DOCTYPE html>
<html>
<head>
    <title>{{ entry.title }}</title>
    <style>
        body {
            font-family: 'DejaVu Sans', sans-serif;
        }
    </style>
</head>
<body>
    <h1>{{ entry.title }}</h1>
    <p>{{ entry.variable }}</p>
</body>
</html>
...

将PDF添加到资产

您可以将生成的PDF文件添加到Craft的资产中。为此，您需要使用@root路径指定文件名。以下示例展示了如何在名为pdffiles的卷上使用它。

{% set pdfOptions = { date: entry.dateUpdated|date('U') } %}
{% set asset = craft.documentHelper.pdfAsset('_pdf/document.twig', alias('@root')~'/example.pdf', entry, pdfOptions, 'pdffiles') %}
{% if asset %}
    <a href="{{asset.url()}}?v={{asset.dateModified|date('U')}}">Download PDF</a>
{% else %}
    The file was not generated.
{% endif %}

在此示例中，时间戳被添加到文件URL中，以确保文件在更改时刷新，这对各种缓存解决方案（如CDN Cache & Preload、Blitz或CDN如Cloudflare）有益。

高级pdfAsset方法选项

默认情况下，PDF的标题基于文件名。但是，您可以使用pdfOptions覆盖此标题以及其他设置。

{% set pdfOptions = {
    ...
    assetTitle: "My Awesome Title",
    assetFilename: "MyAwesome_Filename.pdf",
    assetDelete: true,
    assetSiteId: 2,
    }
%}

在此示例中

  • assetTitle设置了自定义标题。
  • assetFilename设置了自定义文件名。
  • assetDelete当设置为true时，每次此代码运行时，将删除@root路径中的文件并重新生成。
  • assetSiteId设置生成的PDF的站点ID为具有另一个ID的站点。您还可以使用字符串变量（如条目标题）为assetTitle和assetFilename提供变量。
{% set pdfOptions = {
    ...
    assetTitle: entry.title,
    assetFilename: entry.title~".pdf",
    }
%}

这些选项为您提供更大的灵活性，以自定义生成的PDF资产。

在PDF中包含图片

在PDF模板中包含图像有两种方式。

如果您使用的是Image Toolbox插件，您可以像这样包含图像

{% set image = entry.photoFromCMS.one() %}
{% set transformSettings = {
    width: 100,
    height: 200,
    mode: 'stretch'
} %}
{% set options = {
  class: '',
  alt: '',
} %}
...
{{craft.images.picture(image, transformSettings, options)}}

您还可以像这样在不使用插件的情况下在PDF文档中包含一个图像

{% set image = entry.photoFromCMS.first() %}
    {% if image is not null %}
        <img src="{{image.url}}" alt="">
    {% endif %}

前端生成的PDF缩略图

您可以使用PDF Thumbnails by @scandel来在客户端生成PDF缩略图。这需要在/web文件夹中加载pdfThumbnails.js、pdf.js和pdf.worker.js文件。您可以从PDF.js找到pdf.js和pdf.worker.js文件。

以下是一个示例

<script src="{{alias('@web')}}/pdfThumbnails.js" data-pdfjs-src="{{alias('@web')}}/pdf_js/build/"></script>
<script src="{{alias('@web')}}/pdf_js/build/pdf.js"></script>
<script src="{{alias('@web')}}/pdf_js/build/pdf.worker.js"></script>
                {% header "Cache-Control: no-cache" %}
<a href="{{alias('@web')}}{{version("/" ~ craft.documentHelper.pdf('_pdf/document.twig', 'file', 'pdf/example.pdf'  , entry, pdfOptions))}}">
<img class="img-responsive" data-pdf-thumbnail-file="{{alias('@web')}}/pdf/example.pdf" src="{{alias('@web')}}/pdfjs_placeholder.png">

通过将assetThumb选项添加到Assets上的pdfAsset方法来在后端生成并通过PDF Generator生成缩略图显示

要显示添加到Craft CMS Twig模板中的图像缩略图，您可以使用以下选项

{% set pdfOptionsAsset = {
    assetThumb: true
    }
%}
{% set asset = craft.documentHelper.pdfAsset('_pdf/document.twig', alias('@root')~'/test.pdf', entry, pdfOptionsAsset, 'pdfFiles') %}
{% if asset %}
{% set assetThumb = asset.assetThumb %}

<a href="{{asset.url()}}?v={{asset.dateModified|date('U')}}">
  {% if assetThumb %}
  <img src="{{ assetThumb.url() }}?v={{ assetThumb.dateModified|date('U') }}" />
  {% else %}
  The thumbnail is not available
  {% endif %}
</a>
{% else %}

如果您想将图像添加到与PDF文件不同的卷中，您可以使用选项assetThumbVolumeHandle覆盖PDF选项，在此示例中，它将被设置为pdfimages卷处理程序

{% set pdfOptionsAsset = {
    assetThumb: true,
    assetThumbVolumeHandle: "pdfimages"
    }
%}

通过将dumbThumb选项添加到默认的pdf方法，在后台生成并通过PDF生成器显示缩略图

要添加使用旧pdf方法生成的缩略图，您可以使用以下代码

{% set pdfOptionsDumb = {
    date: entry.dateUpdated|date('U'),
    dumbThumb: true,
    }
%}
<a href="{{alias('@web')}}/{{craft.documentHelper.pdf('_pdf/document.twig', 'file', 'pdf/example.pdf', entry, pdfOptionsDumb)}}">
    <img src="{{alias('@web')}}{{ '/pdf/example.jpg' }}" />
</a>

通过外部PDF转换插件在后台生成并显示PDF资产的缩略图

要生成PDF资产的图像缩略图，您可以使用PDF Transform插件。请注意，此功能需要ImageMagick。

以下是生成和显示缩略图的示例

{% set pdfOptions = { date: entry.dateUpdated|date('U') } %}
{% set asset = craft.documentHelper.pdfAsset('_pdf/document.twig', alias('@root')~'/example.pdf', entry, pdfOptions, 'pdffiles') %}
{% if asset %}
<a href="{{asset.url()}}?v={{asset.dateModified|date('U')}}">
    {% set transformedPdf = craft.pdfTransform.render(asset) %}
    <img src="{{ transformedPdf.url }}?v={{transformedPdf.dateModified|date('U')}}" />
</a>
{% endif %}

如果启用了ImageMagick则无法生成缩略图怎么办？

如果您在PDF Transform中遇到以下错误

attempt to perform an operation not allowed by the security policy `PDF' @ error/constitute.c/IsCoderAuthorized/421

错误在我们的插件中，在Craft CMS的/runtime/logs/web.log中，并且图像在pdf或pdfAsset中没有生成

Imagick Error: attempt to perform an operation not allowed by the security policy `PDF' @ error/constitute.c/IsCoderAuthorized/421

这意味着ImageMagick的安全策略阻止了对PDF文件的操作。要修复此问题，您需要修改位于/etc/ImageMagick-6/policy.xml或/etc/ImageMagick-7/policy.xml的policy.xml文件，具体取决于您的ImageMagick版本。

找到并修改与PDF相关的策略，以允许所需的操作。请注意，更改此文件可能会有安全影响。请确保您了解风险和后果。以下是将策略从拒绝所有操作更改为允许读/写操作的示例

<!-- Before -->
<policymap>
  <policymap domain="coder" rights="none" pattern="PDF" />
</policymap>

<!-- After -->
<policymap>
  <policymap domain="coder" rights="read | write" pattern="PDF" />
</policymap>

然后，如果您正在使用PHP FPM服务，请重启它。如果您不确定如何修改此文件，请考虑联系您的托管提供商的支持团队以获得帮助。

自定义PDF文档标题

要为您的PDF设置自定义标题，请在pdfOptions中使用title选项，如下所示

{% set pdfOptions = {
    ...,
    title: "My awesome Title"
} %}

自定义变量

您可以在您的Twig模板中使用自定义变量。为此，请将关联数组或变量添加到pdfOptions数组中的custom参数。此数组或传递的变量的键将在您的Twig模板中作为变量可用。

字符串或数字

要将字符串或数字传递给PDF模板，请在pdfOptions中将它设置为custom变量。

{% set pdfOptions = {
    ...,
    custom: variable
} %}

然后，在您的PDF模板中，您可以调用此自定义变量。

{{custom}}

数组

如果您想将数组传递给PDF模板，请在pdfOptions中的custom变量中定义该数组。

{% set pdfOptions = {
    ...,
        custom: {
       slug: entry.slug,
       created: entry.dateCreated,
       ...
    }
} %}

然后，您可以在PDF模板中访问数组变量。

{{custom.slug}}
{{custom.created.format('d/m/Y')}}

自定义PDF文档中的页面分页

您可以在PDF文档中使用<pagebreak>标签添加分页符。

<p>Content before the page break.</p>
<pagebreak />
<p>Content after the page break.</p>

页面和总页数

您可以使用{PAGENO}和{nbpg}占位符在您的Twig模板、页眉或页脚中添加页码和总页数到您的PDF文档中。

<p>Page {PAGENO} of {nbpg}</p>

仅在条目数据更改时生成PDF文件

您可以将PDF生成器插件设置为仅在条目数据更改时生成新PDF文件。为此，使用以下pdfOptions以确保只有当条目中的数据已更新时才生成PDF。

{% set pdfOptions = {
        date: entry.dateUpdated|date('U'),
    } %}

文件名字符

生成的PDF文件名只能包含字母数字字符、下划线和短横线。在选择PDF文件名时，请确保您只使用安全的字符。以下字符不允许在Windows文件名中使用："："、"/"、"?"、"|"、"<"、">"或"/"。

某些服务器和主机上PDF文件的浏览器缓存问题

一些服务器和托管环境可能会缓存PDF文件，这可能会在您尝试查看生成的最新PDF文件版本时造成问题。为了防止这种情况，您可以在PDF文件的URL中添加一个唯一的查询字符串。

如果您遇到服务器或托管缓存PDF文件的问题，您可以使用静态文件自动版本化插件。此插件为您的PDF添加时间戳，有助于避免缓存问题。

<a href="{{alias('@web')}}{{version("/" ~ craft.documentHelper.pdf('_pdf/document.twig', 'file', 'pdf/book'  ~ '.pdf'  ,entry, pdfOptions))}}">LINK </a>

使用此插件后，您的PDF将带有时间戳，并且与您的托管相关的任何缓存策略问题都将得到解决。以下是PDF链接的示例：

<a href="http://some-domain.com/pdf/book.pdf?v=1668157143">LINK </a>

在任意页面上使用JavaScript下载多个PDF文件

您可以在任何页面上使用JavaScript下载多个PDF文件。为此，您可以使用此示例，并通过pdf方法指定要生成PDF文件的条目。

<script>
{% set pdfOptions = {
    date: entry.dateUpdated|date('U')
} %}
var files = [
    "{{ alias('@web') }}/{{craft.documentHelper.pdf('_pdf/document.twig', 'file', 'pdf/' ~ entry.dateCreated|date('Y-m-d') ~ random(10) ~ '.pdf', entry, pdfOptions)}}",
    "{{ alias('@web') }}/{{craft.documentHelper.pdf('_pdf/document.twig', 'file', 'pdf/' ~ entry.dateCreated|date('Y-m-d') ~ random(10) ~ '.pdf', entry, pdfOptions)}}"
];
for (var i = files.length - 1; i >= 0; i--) {
    var a = document.createElement("a");
    a.target = "_blank";
    a.download = "download";
    a.href = files[i];
    a.click();
};
</script>

在频道部分xxx的数组项上的循环示例

{% set pdfOptions = {
    date: entry.dateUpdated|date('U')
} %}
<script>
var files = [
{% for item in craft.entries.section('xxx').orderBy('title asc').all() %}
    "{{alias('@web')}}/{{craft.documentHelper.pdf('_pdf/document.twig', 'file', 'pdf/' ~ item.id ~ '.pdf', item, pdfOptions)}}"
    {% if loop.last %}{% else %}, {% endif %}
{% endfor %}
];
for (var i = files.length - 1; i >= 0; i--) {
    var a = document.createElement("a");
    a.target = "_blank";
    a.download = "download";
    a.href = files[i];
    a.click();
};
</script>

使用pdfAsset方法的示例

您可以在任何页面上使用JavaScript下载多个PDF文件。为此，您可以使用通过pdfAsset方法循环的pdfs参数来指定要生成PDF文件的条目数组，在本例中是频道部分xxx的项。

{% set pdfs = [] %}
{% for item in craft.entries.section('xxx').orderBy('title asc').all() %}
    {% set pdf = craft.documentHelper.pdfAsset('_pdf/document.twig', 'file', 'pdf/' ~ item.id ~ '.pdf', item, pdfOptions) %}
    {% set pdfs = pdfs|merge([pdf]) %}
{% endfor %}

在您的JavaScript代码中传递Craft CMS中的pdfs，然后您可以遍历传递的pdfs数组并触发每个PDF文件的下载。

<script>
    var pdfs = JSON.parse('{{ pdfs|json_encode|raw }}');
    pdfs.forEach(function(pdf) {
    window.open(pdf.url, '_blank');
    });
</script>

可选包

转到PDF生成器插件，并点击“可选功能以启用”部分。您将看到为每个可选包安装按钮和设置单个设置的列表。

显示QRCode

准备包含您要编码到QRCode中的信息的qrdata字符串。该字符串的格式取决于您想附加的信息类型。您需要在插件设置中的可选面板中安装一个可选包。以下是一些常见的格式：

  • 对于网站链接，您只需使用网站URL，例如https://cooltronic.pl/
  • 对于纯文本，您可以使用任何消息，例如Hello, world!
  • 关于联系方式，您可以使用vCard格式，它是一种用于交换个人数据的标准格式，例如：BEGIN:VCARD\nVERSION:3.0\nN:Potacki;Pawel\nTEL;TYPE=work,voice;VALUE=uri:tel:+99-888-777-666\nEMAIL:pawel@cooltronic.pl\nEND:VCARD
  • 对于WiFi配置，您可以使用WIFI格式，这是一种简单分享网络设置的方法，例如：WIFI:S:MyNetwork;T:WPA;P:MyPassword;;

示例

{% set pdfOptions = {
    ...
    qrdata: "https://cooltronic.pl"
    ...
}
%}

在Twig模板中，使用以下代码将QRCode图像插入您想要的位置

<img src="{{qrimg}}">

其中{{qrimg}}是变量，它存储来自PHP QRCode生成器包的图像。

当您在Craft CMS 3（您需要3.4版本）和4（您需要4.3版本）的自动安装过程中遇到问题时，可以手动安装此可选包以显示QR码生成。以下是安装到您的Craft（@root）主安装目录的示例

# Craft CMS 4, 5.0.0.alpha
composer require chillerlan/php-qrcode:^4.3
# Craft CMS 3
composer require chillerlan/php-qrcode:^3.4

RTL文本方向

PDF生成器插件支持从右到左（RTL）文本方向。要启用RTL文本方向，请在您的HTML Twig模板标记中设置HTML dir属性。例如

<div dir="rtl">This is some text in a right-to-left language.</div>

语言

在mPDF中指定语言，您可以在HTML中使用lang属性。例如

<div lang="ar">هذا نص باللغة العربية</div>

字体

为了使mPDF正确显示字符，您还需要使用支持您所使用语言字符的字体。mPDF包含支持广泛字符的多个字体。您可以使用CSS font-family属性设置字体。例如，要使用Arial字体

div {
    font-family: 'Arial';
}

RTL完整示例

阿拉伯文本的完整示例

<div dir="rtl" lang="ar" style="font-family: Arial;">هذا نص باللغة العربية</div>

添加水印

您可以使用mPDF参数向PDF中添加水印。这可以是图像或文本的形式。

添加图像水印

您可以在PDF中包含PNG或JPG图像作为水印。在watermarkImage参数中指定您的图像的路径和文件扩展名。

例如

{% set pdfOptions = {
    'watermarkImage': 'path/to/your/image.ext'
} %}

将path/to/your/image.ext替换为您的图像的实际路径和文件扩展名。

添加文本水印

您还可以向PDF添加文本水印。只需在watermarkText参数中指定您想要使用的文本。

例如

{% set pdfOptions = {
    'watermarkText': 'My text watermark example'
} %}

将'我的文本水印示例'替换为您想要用作水印的实际文本。

生成PDF目录

您可以根据mPDF ToC规范中的指南创建目录。

此外，我们还可以启用从您的PDF文档中存在的H1-H6标签自动生成目录的功能。您可以通过将autoToC选项设置为true来激活此功能。

例如

{% set pdfOptions = {
    'autoToC': true
} %}

生成PDF书签

可以通过使用<bookmark content="Text" />书签标签手动添加书签。内容属性用于设置书签的文本。您还可以使用可选的level属性来设置书签的嵌套级别。

此外，我们还可以启用从您的PDF文档中存在的H1-H6标签自动生成书签的功能。您可以通过将autoBookmarks选项设置为true来激活此功能。为此，请设置

{% set pdfOptions = {
    'autoBookmarks': true
} %}

要求

  • 此插件支持Craft CMS 3.0或更高版本，包括5.0.0.alpha，4.0或更高版本，从插件的master分支的2.2.0版本开始。
  • 对于Craft CMS版本3.x，我们使用了插件craft3分支的0.x版本（最多到0.4.x版本），该版本已被弃用。请安装版本2.0或更高版本。
  • 对于Craft CMS版本4.x，我们使用了插件master分支的1.x版本（最多到1.3.x版本），该版本已被弃用。请安装版本2.0或更高版本。

支持

关于定制PDF工作的咨询，例如生成模板或修改插件，请通过我们的联系页面联系我们。

致谢

特别感谢为这个项目做出贡献的开发者和测试人员，他们帮助识别和修复了bug。

许可

本项目采用Craft许可证。有关详细信息，请参阅LICENSE.md文件。