kongka/蛋糕PDF

CakePHP插件，用于创建和/或渲染PDF，支持多个PDF引擎。

维护者

详细信息

github.com/kongka/CakePdf

主页

源代码

安装: 8

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 183

类型:cakephp-plugin

4.2.0 2023-01-18 12:11 UTC

Requires

Requires (Dev)

Suggests

Replaces

MIT 9a7558f9b305ba4588a3e59aae58b99e32f7dfa5

This package is auto-updated.

Last update: 2024-09-18 15:57:44 UTC

README

Build Status Total Downloads License

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

插件中包含的引擎

  • DomPdf (^0.8。强烈建议使用 ^2.0，因为低版本存在各种安全漏洞)
  • Mpdf (^8.0.4)
  • Tcpdf (^6.3)
  • WkHtmlToPdf 推荐引擎

社区维护的引擎

需求

安装

使用 Composer

composer require friendsofcake/cakepdf

CakePdf不包含任何支持的PDF引擎，您需要自行安装您打算使用的引擎。

推荐wkhtmltopdf引擎的软件包可以从 https://wkhtmltopdf.org/downloads.html 下载。DomPdf、Mpdf 和 Tcpdf 可以通过以下命令之一使用Composer安装

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

设置

使用 CakePHP 控制台加载插件

./bin/cake plugin load CakePdf

如果您打算使用 PDF视图功能，该功能自动渲染并返回PDF以发送到浏览器，您还应在您的 config/routes.php 文件中注册 pdf 扩展

$routes->scope('/', function (\Cake\Routing\RouteBuilder $routes) {
    $routes->setExtensions(['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
  • download：设置为true以强制下载，仅当使用PdfView时
  • filename：使用强制下载的文档的文件名

示例

Configure::write('CakePdf', [
    'engine' => 'CakePdf.WkHtmlToPdf',
    'margin' => [
        'bottom' => 15,
        'left' => 50,
        'right' => 30,
        'top' => 45
    ],
    'orientation' => 'landscape',
    'download' => true
]);
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()->setOption(
            'pdfConfig',
            [
                'orientation' => 'portrait',
                'filename' => 'Invoice_' . $id
            ]
        );
        $this->set('invoice', $invoice);
    }
}

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

Configure::write('CakePdf', [
    'engine' => [
        'className' => 'CakePdf.WkHtmlToPdf',
        // Options usable depend on the engine used.
        'options' => [
            'print-media-type' => false,
            'outline' => true,
            'dpi' => 96,
            'cover' => [
                'url' => 'cover.html',
                'enable-smart-shrinking' => true,
            ],
            'toc' => true,
        ],

        /**
         * For Mac OS X / Linux by default the `wkhtmltopdf` binary should
         * be available through environment path or you can specify location as:
         */
        // 'binary' => '/usr/local/bin/wkhtmltopdf',

        /**
         * On Windows the engine uses the path shown below as default.
         * You NEED to use the path like old fashioned MS-DOS Paths,
         * otherwise you will get error like:
         * "WKHTMLTOPDF didn't return any data"
         */
        // 'binary' => 'C:\\Progra~1\\wkhtmltopdf\\bin\\wkhtmltopdf.exe',
        
        /**
         * Skip the binary execution checking for many Linux servers when set to `true`.
         * Default value is `false`, which mean we need to check for security reason.
         * It has been used when your Linux server cannot run directly the `/usr/bin/wkhtmltopdf`
         * so, you need to install another package called `xvfb` to support "X server".
         */
        //'skipCheckingExecutableBinary' => false,
        //'binary' => '/usr/bin/xvfb-run /usr/bin/wkhtmltopdf'
    ],
]);

用法

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

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

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

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

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

如果您不想在 URL 中使用 pdf 扩展名，您可以省略在路由配置中注册它。然后，在控制器操作中指定要使用的视图类

$this->viewBuilder()->setClassName('CakePdf.Pdf');

您可以选择使用 download 选项强制 PDF 在浏览器中下载。此外，您还可以使用 filename 选项指定自定义文件名。

$this->viewBuilder()->setOption(
    'pdfConfig',
    [
        'download' => true, // This can be omitted if "filename" is specified.
        'filename' => 'Invoice_' . $id // This can be omitted if you want file name based on URL.
    ]
);

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

您可以使用 CakePdf 库使用视图模板创建原始 PDF 数据。视图文件路径如下 templates/pdf/newsletter.php。布局文件路径如下 templates/layout/pdf/default.php 注意，两种用法类型的布局都在同一目录下，但视图模板使用不同的文件路径。您还可以选择将原始数据写入文件。

示例

$CakePdf = new \CakePdf\Pdf\CakePdf();
$CakePdf->template('newsletter', 'default');
$CakePdf->viewVars(['key' => 'value']);
// 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]);

如果您无法正确获取资产的 URL，您可以使用文件系统路径代替。

<img src="<?= WWW_ROOT ?>img/logo.png" />

注意：由于 v0.12.16，wkhtmltopdf 需要 enable-local-file-access 选项才能使用本地文件系统路径访问资产。您可以通过在引擎配置数组中设置 'enable-local-file-access' => true 来启用它。

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

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