百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
C

CakePdf

> 编程语言
开源

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

372 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

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

CakePdf plugin

Plugin containing CakePdf lib which will use a PDF engine to convert HTML to PDF.

Engines included in the plugin:

  • DomPdf (^3.0)
  • Mpdf (^8.0.4)
  • TcLibPdf (^8) - successor of the deprecated Tcpdf engine
  • Tcpdf (^6.3) - deprecated, the underlying tecnickcom/tcpdf package is deprecated upstream; use TcLibPdf instead
  • WeasyPrint (Recommended if you have the privileges to install something on your server)
  • WkHtmlToPdf (project no longer maintained but binaries still available for various environments)

Community maintained engines:

  • PDFreactor

Requirements

  • One of the following render engines: DomPdf, Mpdf, Tcpdf, WeasyPrint or wkhtmltopdf
  • pdftk (optional) See: http://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/

Installation

Using Composer:

composer require friendsofcake/cakepdf

CakePdf does not include any of the supported PDF engines, you need to install the ones you intend to use yourself.

Check WeasyPrint's installation guide to install it on your system. DomPdf, Mpdf, TcLibPdf and Tcpdf can be installed via composer using one of the following commands:

composer require dompdf/dompdf
composer require tecnickcom/tc-lib-pdf
composer require tecnickcom/tcpdf
composer require mpdf/mpdf

TcLibPdf font setup

Unlike the deprecated Tcpdf engine, tecnickcom/tc-lib-pdf does not bundle any fonts. It loads fonts from generated *.json font files located in a directory referenced by the K_PATH_FONTS constant. Define it once during your application bootstrap, before any PDF is rendered:

php
define('K_PATH_FONTS', '/absolute/path/to/your/fonts');

The directory must contain at least the core fonts you reference (e.g. helvetica.json). See the tc-lib-pdf-font documentation for how to generate font files.

Setup

Loading the plugin using CakePHP's console:

./bin/cake plugin load CakePdf

If you plan to use the PDF view functionality that automatically renders and returns the PDF for sending it to the browser, you should also register the pdf extension in your config/routes.php file:

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

Further setup information can be found in the usage section.

Configuration

Use Configure::write('CakePdf', $config); or in controller use view builder to set view option named pdfConfig (only when used with PdfView). You need to define at least $config['engine']. When using CakePdf directly you can also pass the config array to constructor. The value for engine should have the Plugin.ClassName format without the Engine suffix.

Configuration options:

  • engine: Engine to be used (required), or an array of engine config options
    • className: Engine class to use
    • binary: Binary file to use (Only for weasyprint/wkhtmltopdf)
    • cwd: current working directory (Only for weasyprint/wkhtmltopdf)
    • options: Engine specific options. Currently used for following engine:
      • WkHtmlToPdfEngine: The options are passed as CLI arguments
      • WeasyPrintEngine: The options are passed as CLI arguments
      • TexToPdfEngine: The options are passed as CLI arguments
      • DomPdfEngine: The options are passed to constructor of Dompdf class
      • MpdfEngine: The options are passed to constructor of Mpdf class
      • TcLibPdfEngine: Supports unit, unicode, subsetFont, compress, mode, font (['family', 'style', 'size']), margins (['left', 'top', 'right', 'bottom']) and metadata (['author', 'creator', 'subject', 'keywords'])
  • crypto: Crypto engine to be used, or an array of crypto config options
    • className: Crypto class to use
    • binary: Binary file to use
  • pageSize: Change the default size, defaults to A4 (Needs to be set via CSS for WeasyPrint)
  • orientation: Change the default orientation, defaults to portrait (Needs to be set via CSS for WeasyPrint)
  • margin: Array or margins with the keys: bottom, left, right, top and their values (Needs to be set via CSS for WeasyPrint)
  • title: Title of the document (Needs to be set via CSS for WeasyPrint)
  • delay: A delay in milliseconds to wait before rendering the pdf (wkhtmltopdf only)
  • windowStatus: The required window status before rendering the pdf (wkhtmltopdf only)
  • encoding: Change the encoding, defaults to UTF-8
  • download: Set to true to force a download, only when using PdfView
  • filename: Filename for the document when using forced download

Example:

php
Configure::write('CakePdf', [
    'engine' => 'CakePdf.WeasyPrint',
    'download' => true,
]);
…

The engine and crypto config options can also be arrays with configuration options for the relevant class. For example:

…

Usage

You can use CakePdf in two ways, read carefully which one you actually need. Many people mix both ways and don't get the expected results.

1: Render as PDF (including forced download) in the browser with PdfView

You can create PDF template and layout files for your controller actions and have them automatically rendered. Place the templates in a pdf subdir, for instance templates/Invoices/pdf/view.php, layouts will be in templates/layout/pdf/default.php.

Then for e.g. accessing the URL http://localhost/invoices/view/1.pdf would give you the generated PDF.

Additionally you can map resources by adding Router::mapResources(['Invoices']); to your routes file and you can access the same document at http://localhost/invoices/1.pdf.

In case you don't want to use the pdf extension in your URLs, you can omit registering it in your routes configuration. You can then set the Accept request header to application/pdf to make CakePHP automatically switch to PdfView (required the viewClasses() method to be set as shown above), or explicity switch the view class in your controller action:

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

Instead of having the pdf rendered in the browser itself, you can force it to be downloaded by using download option. Additionally you can specify custom filename using filename options.

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

2: Create PDF for email attachment, file storage etc.

You can use CakePdf to create raw PDF data with a view template. The view file path would look like templates/pdf/newsletter.php. Layout file path would be like templates/layout/pdf/default.php Note that layouts for both usage types are within same directory, but the view templates use different file paths Optionally you can also write the raw data to file.

Example:

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');

Encryption

You can optionally encrypt the PDF with permissions

To use encryption you first need to select a crypto engine. Currently we support the following crypto engines:

  • Pdftk

Usage

Add the following in your bootstrap.

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

Options in pdfConfig:

  • protect: Set to true to enable encryption
  • userPassword (optional): Set a password to open the PDF file
  • ownerPassword (optional): Set the password to unlock the locked permissions
  • one of the above must be present, either userPassword or ownerPassword
  • permissions (optional): Define the permissions

Permissions:

By default, we deny all permissions.

To allow all permissions:

Set 'permission' to true

To allow specific permissions:

Set 'permissions' to an array with a combination of the following available permissions:

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

How to

Ensure css, images etc. are loaded in PDF

Use absolute URLs for static assets in your view templates for PDFs. If you use HtmlHelper::image(), or HtmlHelper::css() make sure you have set fullBase option to true.

For example

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

If you are enable to get URLs for assets working properly, you can try using file system paths instead for the assets.

img/logo.png" />

Note: Since v0.12.16 wkhtmltopdf requires the option enable-local-file-access to be able to use local filesytem paths for assets. You can enable it by setting 'enable-local-file-access' => true in the engine config array.

Get header and footer on all pages

Here are a couple of CSS based solutions you can refer to for easily getting header footer on all PDF pages.

  • https://ourcodeworld.com/articles/read/687/how-to-configure-a-header-and-footer-in-dompdf
  • https://jessicaschillinger.com/print-repeating-header-browser/

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

PHPcakephpcakephp-pluginpdfphp

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言