如何优雅地在CakePHP中生成PDF文档？CakePdf插件助你轻松搞定-composer-PHP中文网

如何优雅地在CakePHP中生成PDF文档？CakePdf插件助你轻松搞定

WBOY

发布： 2025-09-13 13:04:33

原创

274人浏览过

可以通过一下地址学习composer：学习地址

在日常的 web 项目开发中，生成 pdf 文档是一个非常普遍但又常常令人头疼的需求。想象一下这样的场景：

“老板，用户反馈说他们需要把订单详情下载成 PDF 格式，方便打印和归档！” “好的，没问题！”

你信心满满地接下任务，但很快就发现，这远不是一个简单的“没问题”。

遇到的困难：

格式控制的噩梦： HTML 页面直接打印成 PDF 往往排版混乱，CSS 样式丢失，图片不显示，分页不合理，页眉页脚更是无从谈起。
多引擎选择与集成： 市面上有多种 HTML-to-PDF 转换工具，如
```
DomPdf
```
登录后复制
、
```
mPDF
```
登录后复制
、
```
wkhtmltopdf
```
登录后复制
等。它们各有优缺点，但每个都有自己的安装和使用方式。如果项目需要切换引擎，或者需要同时支持多种引擎，那将是巨大的工作量。
框架集成复杂性： 在 CakePHP 这样的 MVC 框架中，如何将 PDF 生成逻辑优雅地融入控制器和视图层？如何处理文件下载、邮件附件等不同的输出需求？这些都需要开发者自己编写大量的适配代码。
静态资源处理： PDF 中包含的图片、CSS 文件路径问题，在转换时常常会找不到资源，导致 PDF 内容不完整。
维护成本： 随着业务发展，PDF 模板可能需要频繁修改，手动维护不同引擎的配置和代码将变得异常繁琐。

面对这些挑战，我们迫切需要一个统一、高效且易于集成的解决方案。幸运的是，在 CakePHP 的生态圈里，

friendsofcake/cakepdf

登录后复制

插件应运而生，它完美地解决了这些痛点。

如何使用 Composer 解决：CakePdf 插件登场

friendsofcake/cakepdf

登录后复制

是一个为 CakePHP 设计的插件，它提供了一个统一的接口来管理和使用各种 PDF 引擎，将复杂的 PDF 生成过程变得简单直观。

立即学习“PHP免费学习笔记（深入）”；

1. 安装 CakePdf 插件

首先，使用 Composer 安装

friendsofcake/cakepdf

登录后复制

：

<pre class="brush:php;toolbar:false;">composer require friendsofcake/cakepdf

登录后复制

2. 安装 PDF 引擎

CakePdf

登录后复制

本身不包含任何 PDF 引擎，你需要根据项目需求选择并安装一个。官方强烈推荐使用

wkhtmltopdf

登录后复制

，它通常能提供最好的渲染效果。

WkHtmlToPdf (推荐): 你需要从 wkhtmltopdf.org 下载并安装对应的二进制文件到你的服务器上。

DomPdf / mPDF / Tcpdf (通过 Composer 安装): 如果你选择其他引擎，可以通过 Composer 安装：

<pre class="brush:php;toolbar:false;">composer require dompdf/dompdf
# 或者
composer require tecnickcom/tcpdf
# 或者
composer require mpdf/mpdf

登录后复制

3. 加载插件并配置路由

在你的 CakePHP 项目中加载插件：

<pre class="brush:php;toolbar:false;">./bin/cake plugin load CakePdf

登录后复制

为了让 CakePHP 能够识别

.pdf

登录后复制

扩展名并自动渲染 PDF，你需要在

config/routes.php

登录后复制

中注册

pdf

登录后复制

扩展：

<pre class="brush:php;toolbar:false;">// config/routes.php
$routes->scope('/', function (CakeRoutingRouteBuilder $routes) {
    $routes->setExtensions(['pdf']); // 添加这一行
    // ... 其他路由
});

登录后复制

CakePdf 的核心优势与实际应用效果

CakePdf

登录后复制

插件提供了两种主要的使用方式，满足不同的业务需求：

场景一：Web 页面直接生成 PDF (PdfView)

华文笔杆

写材料用华文，华文笔杆帮你搞定公文写作

491

查看详情

这是最常见的用法，当用户访问一个带有

.pdf

登录后复制

扩展名的 URL 时，系统会自动将对应的视图渲染成 PDF 并返回给浏览器（可选择下载或在线预览）。

在控制器中启用 PdfView： 在你的控制器中，通过

addViewClasses

登录后复制

方法注册

PdfView

登录后复制

：

<pre class="brush:php;toolbar:false;">// src/Controller/InvoicesController.php
use CakePdfViewPdfView;
use AppControllerAppController; // 确保引入你的AppController

class InvoicesController extends AppController
{
    public function initialize(): void
    {
        parent::initialize();
        $this->addViewClasses([PdfView::class]); // 注册 PdfView
    }

    public function view($id = null)
    {
        $invoice = $this->Invoices->get($id);
        // 可以通过 setOption('pdfConfig') 覆盖全局配置或添加特定配置
        $this->viewBuilder()->setOption(
            'pdfConfig',
            [
                'orientation' => 'portrait', // 纵向
                'filename' => 'Invoice_' . $id . '.pdf', // 设置下载文件名
                'download' => true, // 强制下载
            ]
        );
        $this->set('invoice', $invoice);
    }
}

登录后复制

创建 PDF 视图和布局文件：
```
CakePdf
```
登录后复制
会查找特定的视图文件路径。例如，对于
```
InvoicesController::view()
```
登录后复制
方法，你需要创建：
- 视图文件:
```
templates/Invoices/pdf/view.php
```
  登录后复制
- 布局文件:
```
templates/layout/pdf/default.php
```
  登录后复制
  (如果需要自定义布局)
在这些文件中，你可以像编写普通 HTML 一样编写你的 PDF 内容。

现在，当用户访问

http://localhost/invoices/view/1.pdf

登录后复制

时，就会自动生成并下载

Invoice_1.pdf

登录后复制

文件了！

场景二：生成 PDF 数据用于邮件附件、文件存储等

如果你需要将 PDF 作为邮件附件发送，或者存储到服务器上，而不是直接在浏览器中显示，可以直接使用

CakePdf

登录后复制

类。

<pre class="brush:php;toolbar:false;">// 假设在某个服务或命令中
use CakePdfPdfCakePdf;
use CakeCoreConfigure; // 用于读取配置

// 确保 CakePdf 配置已加载，例如在 bootstrap.php 或这里临时配置
Configure::write('CakePdf', [
    'engine' => 'CakePdf.WkHtmlToPdf', // 指定使用的引擎
    'margin' => [
        'bottom' => 15, 'left' => 15, 'right' => 15, 'top' => 15,
    ],
    'orientation' => 'portrait',
    'encoding' => 'UTF-8',
]);

$CakePdf = new CakePdf();
// 指定要渲染的视图模板 (相对于 templates/pdf/ 目录)
$CakePdf->template('newsletter', 'default');
// 传递视图变量
$CakePdf->viewVars(['title' => '最新资讯', 'content' => '这里是详细的资讯内容...']);

// 获取 PDF 文件的二进制字符串
$pdfData = $CakePdf->output();

// 将 PDF 数据写入文件
$filePath = APP . 'files' . DS . 'newsletter.pdf';
$CakePdf->write($filePath);

// 现在你可以将 $pdfData 作为邮件附件发送，或者使用 $filePath
echo "PDF 已生成并保存到: " . $filePath;

登录后复制

灵活的配置选项

CakePdf

登录后复制

提供了丰富的配置选项，让你能精细控制 PDF 的生成：

<pre class="brush:php;toolbar:false;">// 在 config/bootstrap.php 或控制器中配置
Configure::write('CakePdf', [
    'engine' => [
        'className' => 'CakePdf.WkHtmlToPdf', // 引擎类名
        'binary' => '/usr/local/bin/wkhtmltopdf', // WkHtmlToPdf 二进制文件路径 (Linux/Mac)
        // 'binary' => 'C:\Progra~1\wkhtmltopdf\bin\wkhtmltopdf.exe', // Windows 路径
        'options' => [ // 传递给 wkhtmltopdf 的 CLI 参数
            'print-media-type' => false,
            'outline' => true,
            'dpi' => 96,
            'enable-local-file-access' => true, // 允许访问本地文件系统路径
        ],
    ],
    'pageSize' => 'A4', // 页面大小
    'orientation' => 'landscape', // 横向
    'margin' => [ // 边距
        'bottom' => 15, 'left' => 50, 'right' => 30, 'top' => 45,
    ],
    'title' => '我的自定义 PDF 标题',
    'encoding' => 'UTF-8',
    'download' => false, // 默认不强制下载
    'filename' => 'document.pdf', // 默认文件名
    // ... 更多选项
]);

登录后复制

确保 CSS、图片等静态资源正确加载

这是一个常见问题。为了让 PDF 引擎能够正确加载 CSS 和图片，你需要：

使用绝对 URL： 在视图模板中，使用

HtmlHelper::image()

登录后复制

或

HtmlHelper::css()

登录后复制

时，将

fullBase

登录后复制

选项设置为

true

登录后复制

。

<pre class="brush:php;toolbar:false;">echo $this->Html->image('logo.png', ['fullBase' => true]);
echo $this->Html->css('bootstrap.css', ['fullBase' => true]);

登录后复制

使用文件系统路径： 如果绝对 URL 仍有问题，可以直接使用文件系统路径（需要
```
wkhtmltopdf
```
登录后复制
的
```
enable-local-file-access
```
登录后复制
选项为
```
true
```
登录后复制
）。
```
<pre class="brush:php;toolbar:false;">@@##@@img/logo.png" />
```
登录后复制