README

包含 CakePdf 库的插件，该库将使用 PDF 引擎将 HTML 转换为 PDF。

当前引擎

DomPdf (^0.8)
Mpdf (^7.0)
Tcpdf (^6.2)
WkHtmlToPdf 推荐引擎

要求

CakePHP 3.4+
以下任一渲染引擎：DomPdf、Mpdf、Tcpdf 或 wkhtmltopdf
pdftk（可选）见：http://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/

安装

composer require friendsofcake/cakepdf

CakePdf 不包含任何支持的 PDF 引擎，您需要自行安装您打算使用的引擎。推荐的 WkHtmlToPdf 引擎可以从 http://wkhtmltopdf.org/ 下载，默认情况下 CakePdf 期望 WkHtmlToPdf 二进制文件位于 /usr/bin/wkhtmltopdf。如果您在 Windows 上使用 WkHtmlToPdf，请删除路径名称中的任何空格。例如使用 C:/Progra~1/wkhtmltopdf/bin/wkhtmltopdf.exe

DomPdf、Mpdf 和 Tcpdf 可以通过 Composer 使用以下命令之一安装

composer require dompdf/dompdf
composer require tecnickcom/tcpdf
composer require mpdf/mpdf

设置

在 config/bootstrap.php 中添加

Plugin::load('CakePdf', ['bootstrap' => true]);

或使用 CakePHP 的控制台

./bin/cake plugin load CakePdf -b

如果您计划使用PDF 视图功能，该功能会自动渲染并返回 PDF 以发送到浏览器，您还应在您的 config/routes.php 文件中注册 pdf 扩展，全局注册在受影响的路由之前，或者针对特定的路由范围

Router::extensions(['pdf']);

或针对特定路由范围

Router::scope('/', function (\Cake\Routing\RouteBuilder $routes) {
    $routes->addExtensions(['pdf']);
    // ...
});

有关进一步设置的信息，请参阅使用部分。

配置

使用 Configure::write('CakePdf', $config); 或设置控制器属性 $pdfConfig（仅在用于 PdfView 时）。您需要定义至少 $config['engine']。当直接使用 CakePdf 时，您也可以将配置数组传递给构造函数。引擎的值应采用 Plugin.ClassName 格式，不带引擎后缀。

配置选项

engine：要使用的引擎（必需），或引擎配置选项的数组
- className：要使用的引擎类
- binary：要使用的二进制文件（仅适用于 WkHtmlToPdf）
- cwd：当前工作目录（仅适用于 WkHtmlToPdf）
- options：特定于引擎的选项。目前用于以下引擎
  - WkHtmlToPdfEngine：选项作为 CLI 参数传递
  - TexToPdfEngine：选项作为 CLI 参数传递
  - DomPdfEngine：选项传递给 Dompdf 类的构造函数
  - MpdfEngine：选项传递给 Mpdf 类的构造函数
crypto：要使用的加密引擎，或加密配置选项的数组
- className：要使用的加密类
- binary：要使用的二进制文件
pageSize：更改默认大小，默认为 A4
orientation：更改默认方向，默认为纵向
margin：具有以下键的边距数组：bottom、left、right、top 以及它们的值
title：文档标题
delay：在渲染 PDF 之前等待的延迟（以毫秒为单位）
windowStatus：渲染 PDF 之前所需的窗口状态
encoding：更改编码，默认为 UTF-8
下载：设置为 true 以强制下载，仅当使用 PdfView 时
filename：强制下载时文档的文件名

示例

<?php
    Configure::write('CakePdf', [
        'engine' => 'CakePdf.WkHtmlToPdf',
        'margin' => [
            'bottom' => 15,
            'left' => 50,
            'right' => 30,
            'top' => 45
        ],
        'orientation' => 'landscape',
        'download' => true
    ]);
?>

<?php
    class InvoicesController extends AppController
    {
        // In your Invoices controller you could set additional configs,
        // or override the global ones:
        public function view($id = null)
        {
            $invoice = $this->Invoice->get($id);
            $this->viewBuilder()->options([
                'pdfConfig' => [
                    'orientation' => 'portrait',
                    'filename' => 'Invoice_' . $id
                ]
            ]);
            $this->set('invoice', $invoice);
        }
    }
?>

配置选项 engine 和 crypto 也可以是包含相关类配置选项的数组。例如

    Configure::write('CakePdf', [
        'engine' => [
            'className' => 'CakePdf.WkHtmlToPdf',
            // Mac OS X / Linux is usually like:
            'binary' => '/usr/local/bin/wkhtmltopdf',
            // On Windows environmnent you NEED to use the path like
            // old fashioned MS-DOS Paths, otherwise you will keep getting:
            // WKHTMLTOPDF didn't return any data
            // 'binary' => 'C:\\Progra~1\\wkhtmltopdf\\bin\\wkhtmltopdf.exe',
            // 'cwd' => 'C:\\Progra~1\\wkhtmltopdf\\bin',
	        'options' => [
	            'print-media-type' => false,
	            'outline' => true,
	            'dpi' => 96
	        ],
        ],
    ]);

用法

您可以使用 CakePdf 以两种方式，请仔细阅读您实际上需要哪种。许多人混合使用两种方式，但没有得到预期的结果。

1：使用 PdfView 在浏览器中以 PDF 格式渲染（包括强制下载）

您可以为您的控制器动作创建 PDF 视图和布局文件，并将它们自动渲染。将视图模板放置在 'pdf' 子目录中，例如 src/Template/Invoices/pdf/view.ctp，布局将在 src/Template/Layout/pdf/default.ctp 中。

请确保您的 InvoicesController 类加载了 RequestHandler 组件，并浏览到 https:///invoices/view/1.pdf

此外，您可以通过在路由文件中添加 Router::mapResources(['Invoices']); 来映射资源，然后您可以在 https:///invoices/1.pdf 访问相同的文档。

如果您不希望在您的 URL 中使用 pdf 扩展名，则可以省略在路由配置中注册它。然后在您的控制器动作中调用 RequestHandler::render() 以切换视图类和模板路径。

$this->RequestHandler->renderAs($this, 'pdf', ['attachment' => 'filename.pdf']);

2：创建 PDF 用于电子邮件附件、文件存储等。

您可以使用 CakePdf 库使用视图模板创建原始 PDF 数据。视图文件路径看起来像 src/Template/Pdf/newsletter.ctp。布局文件路径将像 src/Template/Layout/pdf/default.ctp。注意，两种用法类型的布局都在同一目录中，但视图模板使用不同的文件路径。您还可以选择将原始数据写入文件。

示例

<?php
    $CakePdf = new \CakePdf\Pdf\CakePdf();
    $CakePdf->template('newsletter', 'default');
    $CakePdf->viewVars($this->viewVars);
    // Get the PDF string returned
    $pdf = $CakePdf->output();
    // Or write it to file directly
    $pdf = $CakePdf->write(APP . 'files' . DS . 'newsletter.pdf');

加密

您可以选择使用权限加密 PDF

要使用加密，您首先需要选择一个加密引擎。目前我们支持以下加密引擎

Pdftk

用法

在您的引导程序中添加以下内容。

Configure::write('CakePdf.crypto', 'CakePdf.Pdftk');

pdfConfig 中的选项

protect：设置为 true 以启用加密
userPassword（可选）：设置打开 PDF 文件的密码
ownerPassword（可选）：设置解锁锁定权限的密码
以上之一必须存在，即 userPassword 或 ownerPassword
permissions（可选）：定义权限

权限

默认情况下，我们拒绝所有权限。

要允许所有权限

将 'permission' 设置为 true

要允许特定权限

将 'permissions' 设置为一个数组，其中包含以下可用的权限组合

print
degraded_print
modify,
assembly,
copy_contents,
screen_readers,
annotate,
fill_in

如何操作

确保 CSS、图片等在 PDF 中加载

对于 PDF 的视图模板中的静态资源使用绝对 URL。如果您使用 HtmlHelper::image() 或 HtmlHelper::css()，请确保已将 fullBase 选项设置为 true。

例如

echo $this->Html->image('logo.png', ['fullBase' => true]);
echo $this->Html->css('bootstrap.css', ['fullBase' => true]);

在所有页面上获取页眉和页脚

这里有一些基于 CSS 的解决方案，您可以在所有 PDF 页面上轻松获取页眉和页脚。

感谢

非常感谢 Kim Biesbjerg 和 Jelle Henkens 对其贡献。想要您的名字也在这里吗？创建一个用于改进/其他 PDF 引擎的 pull request。

danny3b / cakepdf

维护者

详细信息