informatica-cne/php-pdf

维护者

详细信息

github.com/InformaticaCNE/PHPPdf

源代码

安装: 2

依赖项: 1

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 77

1.2.11 2019-01-31 12:12 UTC

Requires

Requires (Dev)

Suggests

MIT 0fe4118b31557ddb1169698622273b224086b67d

pdfPHPPdf

This package is auto-updated.

Last update: 2024-09-23 19:58:47 UTC

README

Build Status

示例

示例文档位于 "examples" 目录中。 "index.php" 文件是浏览示例的网页界面，"cli.php" 是控制台界面。通过网页界面，文档以 pdf 和 jpeg 格式提供（jpeg 格式需要 Imagick）。

文档

目录

  1. 简介
  2. 安装
  3. Symfony2 包
  4. 常见问题解答
  5. 文档解析和创建 PDF 文件
  6. 基本文档结构
  7. 继承
  8. 样式表结构
  9. 颜色板
  10. 标准标签
  11. 属性
  12. 复杂属性
  13. 单位
  14. 条形码
  15. 图表
  16. 超链接
  17. 书签
  18. 便签
  19. 重复的页眉和页脚
  20. 水印
  21. 页码
  22. 将 PDF 文档用作模板
  23. 分栏显示单独页面
  24. 断页和断栏
  25. 元数据
  26. 配置
  27. Markdown 支持
  28. [图像生成引擎] (#image-generation)
  29. 已知限制
  30. 待办事项 - 计划
  31. 技术要求

简介

PHPPdf 是一个库，将 XML 文档转换为 PDF 文档或图形文件。XML 源文档类似于 HTML，但在属性名称和属性、标签属性以及存在许多非标准标签方面有很多差异，并不是所有 HTML 标签都受支持，样式表在 XML 文档中描述，而不是在 CSS 中。

该库的假设不是 HTML -> PDF / JPEG / PNG，而是 XML -> PDF / JPEG / PNG 转换。一些标签和属性与 HTML 中相同，以降低该库的学习曲线。

安装

PHPPdf 可在 packagist.org 上找到，因此您可以使用 composer 下载此库及其所有依赖项。

(将以下内容添加到 composer.json 文件中的 require 部分)

    "psliwa/php-pdf": "*"

您应该选择最后一个稳定版本（或稳定版本的通配符），通配符字符 ("*") 只是一个示例。

如果您想使用条形码或图像生成等功能，应添加额外的依赖项

    "zendframework/zend-barcode": ">=2.0.0,<2.4",
    "zendframework/zend-validator": ">=2.0.0,<2.4",
    "imagine/Imagine": ">=0.2.0,<0.6.0"

Symfony2 包

有一个 Symfony2 包，它将此库与 Symfony2 框架集成。

常见问题解答

重音符号不显示，我该怎么做？

您应该设置一个支持您所使用的编码的字体，并将此编码设置为 "page" 和/或 "dynamic-page" 标签的 "encoding" 属性。PHPPdf 提供了一些支持 utf-8 编码的免费字体，例如 DejaVuSans。 "Font" 示例展示了如何通过使用样式表来更改字体类型。

您还可以添加自定义字体，为此您应该准备 xml 配置文件并按照以下方式配置 Facade 对象

    <!-- xml config file code -->
    <fonts>
        <font name="DejaVuSans">
            <normal src="%resources%/fonts/DejaVuSans/normal.ttf" /><!-- "%resources%" will be replaced by path to PHPPdf/Resources directory -->
            <bold src="%resources%/fonts/DejaVuSans/bold.ttf" />
            <italic src="%resources%/fonts/DejaVuSans/oblique.ttf" />
            <bold-italic src="%resources%/fonts/DejaVuSans/bold+oblique.ttf" />
            <light src="%resources%/fonts/DejaVuSans/light.ttf" />
            <light-italic src="%resources%/fonts/DejaVuSans/light+oblique.ttf" />
        </font>
    </fonts>
//php code
$loader = new PHPPdf\Core\Configuration\LoaderImpl();
$loader->setFontFile(/* path to fonts configuration file */);
$builder = PHPPdf\Core\FacadeBuilder::create($loader);
$facade = $builder->build();
<!-- xml document code -->
<pdf>
    <dynamic-page encoding="UTF-8" font-type="DejaVuSans">
    </dynamic-page>
</pdf>

您可以在 配置 部分找到更多详细信息。

生成包含 png 图像的简单 PDF 文件需要很长时间和内存，我该怎么做？

PHPPdf 使用的是 Zend_Pdf 库，它对未压缩的 png 文件支持较差。您应该压缩 png 文件。

我如何更改页面大小/方向？

要设置页面尺寸，您使用页面或动态页面标签的 "page-size" 属性。

此属性的值语法为 "width:height"。

但是，也有一些标准预定义值

  • 格式：从 4A0 到 A10
  • B 格式：从 B0 到 B10
  • C 格式：从 C0 到 C10
  • 美国尺寸：法律和信函

所有格式均支持纵向和横向。

示例

<page page-size="100:50">text</page>
<page page-size="a4">text</page>
<page page-size="letter-landscape">text</page>

文档解析和创建PDF文件

使用库的最简单方法是

//register the PHPPdf and vendor (Zend_Pdf and other dependencies) autoloaders
require_once 'PHPPdf/Autoloader.php';
PHPPdf\Autoloader::register();
PHPPdf\Autoloader::register('/path/to/library/lib/vendor/Zend/library');

//if you want to generate graphic files
PHPPdf\Autoloader::register('sciezka/do/biblioteki/lib/vendor/Imagine/lib');

$facade = new PHPPdf\Core\Facade(new PHPPdf\Core\Configuration\Loader());

//$documentXml and $stylesheetXml are strings contains XML documents, $stylesheetXml is optional
$content = $facade->render($documentXml, $stylesheetXml);

header('Content-Type: application/pdf');
echo $content;

基础文档结构

该库基于类似HTML的XML格式，但此格式不是HTML - 一些标签不同，一些属性的解析与HTML和CSS标准不同，添加属性的方式也不同。

一个简单的文档具有以下结构

<pdf>
    <dynamic-page>
        <h1>Header</h1>
        <p>paragraph</p>
        <div color="red">Layer</div>
        <table>
            <tr>
                <td>Column</td>
                <td>Column</td>
            </tr>
        </table>
    </dynamic-page>
</pdf>

强烈建议添加DOCTYPE声明，以便在值上替换HTML实体。

    <!DOCTYPE pdf SYSTEM "%resources%/dtd/doctype.dtd">

文档的根名称必须是"pdf"。 "dynamic-page"标签是一个可自动分页的页面。 "page"标签是替代品，表示单个、不可分页的页面。

属性设置的方式与HTML不同。

为了设置背景和边框，您需要使用复杂属性，其中属性名称的第一部分是复杂属性类型，第二部分是此属性的属性。

复杂属性部分由点（"."）分隔。

设置复杂属性的另一种方法是使用"complex-attribute"标签。

示例

<pdf>
    <dynamic-page>
        <div color="red" border.color="black" background.color="pink">
            This text is red on pink backgroun into black border
        </div>
    </dynamic-page>
</pdf>

替代语法（"stylesheet"标签）

<pdf>
    <dynamic-page>
        <div>
            <stylesheet>
                <attribute color="red" />
                <complex-attribute name="border" color="black" />
                <complex-attribute name="background" color="pink" />
            </stylesheet>
            This text is red on pink backgroun into black border
        </div>
    </dynamic-page>
</pdf>

属性可以设置为XML属性，直接跟在标签名称之后，或使用所提到的"stylesheet"标签。PHPPdf XML方言中没有HTML的"style"属性。

该库在尊重标签和属性的正确性方面非常严格。如果检测到不存在标签或属性，文档解析器将停止并抛出异常。

继承

在HTML中，"id"属性有不同的用法。id属性用于在继承时标识标签。

"name"属性也可以用作"id"的别名。

id必须在整个文档中是唯一的，否则会抛出解析错误。

示例

<pdf>
    <dynamic-page>
        <div id="layer-1" color="red" font-type="judson" font-size="16px">
            <stylesheet>
                <complex-attribute name="border" color="green" />
            </stylesheet>
            Layer 1
        </div>
        <div extends="layer-1">
            Layer 2 inherits style (type, simple and complex attributes) from layer 1)
        </div>
    </dynamic-page>
</pdf>

第二层继承所有属性（简单和复杂），以及来自外部样式表的属性。

属性设置中的优先级

  1. 元素标签中的样式表标签直接
  2. 标签名称之后直接设置属性（XML属性）
  3. 来自外部样式表的属性
  4. 从父标签继承的属性

示例

<pdf>
    <page>
        <div id="1" color="#cccccc" height="100px" text-align="right">
        </div>
        <div extends="1" color="#aaaaaa" height="150px">
            <stylesheet>
                <attribute name="height" value="200px" />
            </stylesheet>
        </div>
    </page>
</pdf>

第二个"div"现在将具有以下属性

  • text-align: right
  • color: #aaaaaa
  • height: 200px

样式表结构

样式表定义在外部文件中，支持样式表的短和长属性声明。

样式表的语法

简短样式

<stylesheet>
    <!-- style attributes are embeded as xml attributes, class attribute has the same meaning as in HTML/CSS -->
    <div class="class" font-size="12px" color="gray" background.color="yellow">
        <!-- nested element, equivalent CSS selector syntax: "div.class p" -->
        <p margin="10px 15px">
        </p>
    </div>

    <!-- equivalent CSS selector syntax: ".another-class", "any" tag is wildcard (mean any tag) -->
    <any class="another-class" text-align="right">
    </any>

    <h2 class="header">
        <span font-size="9px">
        </span>
        
        <div font-style="bold">
        </div>
    </h2>
</stylesheet>

长样式

<stylesheet>
    <div class="class">
        <!-- simple and complex attributes are nested in "div.class" selector path -->
        <attribute name="font-size" value="12px" />
        <attribute name="color" value="grey" />
        <!-- equivalent of background.color attribute -->
        <complex-attribute name="background" color="yellow" />

        <!-- another nested element, equivalent CSS selector syntax: "div.class p" -->
        <p>
            <attribute name="margin" value="10px 15px" />
        </p>
    </div>

    <!-- equivalent CSS selector syntax: ".another-class", "any" tag is wildcard (mean any tag) -->
    <any class="another-class">
        <attribute name="text-align" value="right" />
    </any>

    <h2 class="header">
        <span>
            <attribute name="font-size" value="9px" />
        </span>
        <div>
            <attribute name="font-style" value="bold" />
        </div>
    </h2>
</stylesheet>

颜色板

PHPPdf支持颜色板，即逻辑名称到实际颜色的映射。

颜色板为您提供创建或覆盖默认命名颜色的机会。默认情况下，PHPPdf支持来自W3C标准的命名颜色（例如"black" = "#000000"）。

您可以使用颜色板来实现DRY原则，因为有关使用的颜色的信息将保存在一个地方。您还可以生成具有不同颜色板的文档。

示例

<!-- colors.xml file -->
<colors>
    <color name="header-color" hex="#333333" />
    <color name="line-color" hex="#eeeeee" />
</colors>

<!-- stylesheet.xml file -->
<h2 color="header-color" />
<hr background-color="line-color" />
<table>
    <td border-color="line-color" />
</table>

<!-- document.xml file -->
<pdf>
    <page>
        <h2>Header</h2>
        <hr />
        <table>
            <tr>
                <td>Data</td>
                <td>Data</td>
            </tr>
        </table>
    </page>
</pdf>
    //php code
    use PHPPdf\DataSource\DataSource;
    
    $facade = ...;

    $content = $facade->render(
        DataSource::fromFile(__DIR__.'/document.xml'),
        DataSource::fromFile(__DIR__.'/stylesheet.xml'),
        DataSource::fromFile(__DIR__.'/colors.xml')
    );

标准标签

该库支持主要的HTML标签：div, p, table, tr, td, b, strong, span, a, h1, h2, h3, h4, h5, img, br, ul, li

此外，还有一些非标准标签

  • dynamic-page - 可自动分页的页面
  • page - 具有固定大小的单页
  • 弹性页面 - 与其他标签（例如 "div"）一样，根据其子元素的高度自适应高度的单一页面。标题、页脚、水印、模板文档属性不适用于此标签。特别适用于图形文件生成（图像引擎）。
  • 分页、列分页、分页 - 分割页面或列，此标签必须是 "dynamic-page" 或 "column-layout" 的直接子标签！
  • 列布局 - 在列上分离工作空间，附加属性：列数、列间边距、等宽列
  • 条码 - 更多信息请见条码章节
  • 圆形 - 边框和背景均为圆形的元素。附加属性：半径（它覆盖宽度和高度属性）
  • 饼图 - 可用于绘制简单饼图的元素（更多信息请见图表章节）。

有些标签仅是属性的容器，或一组标签等。

  • 样式表 - 父标签的样式表
  • 属性 - 简单属性声明，为 "stylesheet" 标签的直接子标签。此元素的必需属性：name - 属性名称，value - 属性值
  • 复杂属性 - 复杂属性声明，为 "stylesheet" 标签的直接子标签。此元素的必需属性：name - 复杂属性名称
  • 占位符 - 定义父标签的占位符。占位符的子标签对每个父标签都是特定的。它应该是父标签的第一个标签
  • 元数据 - 定义 PDF 文档的元数据，为文档根的直接子标签
  • 行为 - 定义父标签的行为。支持的行为：href、ref、书签、note（行为与具有相同名称的属性的行为相同）

属性

  • 宽度与高度：刚性设置高度和宽度，支持的单位在单独的章节中描述。支持相对值，以百分比表示。
  • 最大宽度、最大高度：设置元素的最大尺寸
  • 边距（上边距、下边距、左边距、右边距）：类似于 HTML/CSS 中的边距。合并的边距被汇总。对于侧边距，可能的值为 "auto"，它的工作方式类似于 HTML/CSS。
  • 填充（上填充、下填充、左填充、右填充）：与 HTML/CSS 中的工作方式相似
  • 字体类型 - 字体名称必须在 fonts.xml 配置文件中出现，否则将抛出异常
  • 字体大小 - 点的大小，没有单位
  • 字体样式 - 允许的值：normal、bold、italic、bold-italic、light、light-italic
  • 颜色 - 文本颜色。支持 HTML/CSS 风格的值
  • 可断开 - 如果为 true，则元素能够在多个页面中断裂。大多数标签的默认值为 true。
  • 浮动 - 与 HTML/CSS 中的工作方式相似但不同。允许的值：left|none|right，默认值为 none
  • 行高 - 与 HTML/CSS 中的工作方式相似。默认值：1.2*字体大小
  • 文本对齐 - 与 HTML/CSS 中的工作方式相同。允许的值：left|center|right|justify，默认值为 left。
  • 文本装饰 - 允许的值：none、underline、overline、line-through
  • 断开 - 在具有此属性的元素的所有者处断开页面或列。具有此属性的元素的所有者必须是 dynamic-page 或 column-layout 标签的直接子标签！
  • colspan、rowspan - 与 HTML 中的工作方式相似（待办事项：rowspan 尚未实现）
  • href - 元素应链接的外部 URL
  • ref - 所有者应链接的元素的 id
  • 书签 - 创建与给定标题关联的标签的书签
  • 备注 - 创建与标签关联的贴纸
  • dump - 允许的值：true 或 false。创建包含调试信息（属性、位置等）的贴纸
  • rotate - 元素旋转的角度。此属性尚未完全实现，仅对水印有效（请参阅“水印”部分）。可能的值：XXdeg（度），XX（弧度），对角线，-对角线。
  • alpha - 可能的值：从0到1。元素及其子元素的透明度。
  • line-break - 换行（true或false），默认情况下仅对"br"标签设置为true。
  • style - 与HTML中相同，此属性可以用来设置其他属性，例如：style="width: 100px; height: 200px; margin: 20px 0;"。每个属性都必须以";"字符结束，即使是最后一个。
  • ignore-error（仅适用于img标签） - 忽略文件加载错误或抛出异常？默认为false，表示将抛出异常。
  • keep-ratio（仅适用于img标签） - 即使设置的尺寸比与原始源图像的尺寸比不同，也会保持图像比例。默认为false。
  • position - 与HTML中相同。允许的值：static（默认），relative，absolute。
  • left和top - 与HTML中相同，与position relative或absolute一起使用。right和bottom不受支持。

复杂属性

可以通过“attributeName.attributeProperty”或“attributeName-attributeProperty”表示法设置复杂属性。

例如：border.color="black"或border-color="black"

  • border

    • color: 边框颜色
    • style: 可能的值：solid（实线），dotted（预定义的点线）或由空格分隔的整数定义
    • type: 将显示哪些边缘 - 默认 "top+bottom+left+right"（所有边缘）。"none"值是可能的（它禁用边框）
    • size: 边框大小
    • radius: 以长度单位为单位的角圆度（注意：如果设置了此参数，则type参数将被忽略，圆角边框始终是完整的 - 这将在未来修复）
    • position: 边框相对于原始位置的位置。正值扩展边框，负值减小边框。通过此参数的操作，您可以获得复杂的边框模式，例如添加不同样式和位置的另一个边框。

  • background

    • color: 背景颜色
    • image: 背景图像
    • repeat: 图像重复的方式（none|x|y|all）
    • radius: 以长度单位为单位的背景角圆度（目前仅适用于颜色背景）
    • use-real-dimension: 仅用于页面（或动态页面）。如果用于填充，则为true，否则为false。
    • image-width: 背景图像的自定义宽度，允许使用百分比值
    • image-height: 背景图像的自定义高度，允许使用百分比值
    • position-x: 背景图像的水平位置，允许的值：left，center，right或数值（默认：left）
    • position-y: 背景图像的垂直位置，允许的值：top，center，bottom或数值（默认：top）

可以在同一类型中添加多个复杂属性（例如3个不同的边框）。

您可以通过使用"stylesheet"标签而不是简写表示法来实现这一点。

<pdf>
    <dynamic-page>
        <div>
            <stylesheet>
                <!-- Top and bootom edges are red, side edges are yellow-gray --> 
                <complex-attribute name="border" color="red" type="top+bottom" />
                <complex-attribute id="borderLeftAndRight" name="border" color="yellow" type="left+right" size="4px" />
                <complex-attribute id="outerBorderLeftAndRight" name="border" color="gray" type="left+right" size="2px" position="1px" />
            </stylesheet>
        </div>
    </dynamic-page>
</pdf>

在此示例中，第二个边框有一个"borderLeftAndRight"标识符，如果此边框没有id，第二个边框的属性将与第一个边框的属性合并。

请记住，默认标识符"id"与"name"属性相同。复杂属性的"id"属性与标签的"id"属性（用于继承）无关。

可以创建与前面示例中相同的复杂边框（outerBorderLeftAndRight）。

单位

支持数值属性的单元

  • in（英寸）
  • cm（厘米）
  • mm（毫米）
  • pt（点）
  • pc（派卡）*
  • px（像素）
    • %（百分比 - 仅用于宽度和高度）。

当前不支持的单位是：em 和 ex

当缺少单位时（例如：font-size="10"），则默认单位是点（pt）。1pt = 1/72 英寸

条形码

条形码由 <barcode> 标签支持。

PHPPdf 使用 Zend\Barcode 库来生成条形码。

示例

<pdf>
    <dynamic-page>
        <barcode type="code128" code="PHPPdf" />
    </dynamic-page>
</pdf>

<barcode> 标签支持大多数标准属性，还有一些其他属性

  • type - 条形码类型，支持值：code128、code25、code25interleaved、code39、ean13、ean2、ean5、ean8、identcode、itf14、leitcode、planet、postnet、royalmail、upca、upce
  • draw-code - 等同于 Zend\Barcode 的 drawCode 选项
  • bar-height - 等同于 Zend\Barcode 的 barHeight 选项
  • with-checksum - 等同于 Zend\Barcode 的 withChecksum 选项
  • with-checksum-in-text - 等同于 Zend\Barcode 的 withChecksumInText 选项
  • bar-thin-width - 等同于 Zend\Barcode 的 barThinWidth 选项
  • bar-thick-width - 等同于 Zend\Barcode 的 barThickWidth 选项
  • rotate - 等同于 Zend\Barcode 的 orientation 选项

您可以在 Zend\Barcode 文档 中找到这些选项及其默认值的描述。

为了渲染文本条形码，您不能使用以下嵌入的 PDF 字体：courier、times-roman 和 helvetica。这将被很快修复。

图表

PHPPdf 支持绘制简单的图表。

目前仅支持简单的饼图。

示例

<pdf>
    <dynamic-page>
        <pie-chart radius="200px" chart-values="10|20|30|40" chart-colors="black|red|green|blue"></pie-chart>
    </dynamic-page>
</pdf>

<pie-chart> 标签有三个额外的属性

  • radius - 图表的半径
  • chart-values - 图表的值，它们的总和必须是100。每个值必须用 "|" 分隔。
  • chart-colors - 每个值的颜色。每个颜色必须用 "|" 分隔。

超链接

库支持外部和内部超链接。

外部超链接链接到 URL，而内部链接链接到 PDF 文档中的其他标签。

示例

<pdf>
    <dynamic-page>
        <a href="http://google.com">go to google.com</a>
        <br />
        <a ref="some-id">go to another tag</a>
        <a href="#some-id">go to another tag</a> <!-- anchor style ref -->
        <page-break />
        <p id="some-id">Yep, this is another tag! ;)</p>
    </dynamic-page>
</pdf>

每个元素都有 "href" 和 "ref" 属性，甚至 div。您不能在 "a" 标签内嵌套元素。

如果您想使用 img 元素作为链接，您应该在 img 标签中直接使用 href（外部链接）或 ref（内部链接）属性。

书签

创建书签的首选方式是使用 "behaviours" 标签。

这不会限制文档的结构，父书签的所有者不必是子书签所有者的父级。

示例

<pdf>
    <dynamic-page>
	    <div>
	        <behaviours>
	            <bookmark id="1">parent bookmark</bookmark>
	        </behaviours>
	        Some content
	    </div>
	    <div>
	        <behaviours>
	            <bookmark parentId="1">children bookmark</bookmark>
	        </behaviours>
	        Some another content
	    </div>
	    <div>
	        <behaviours>
	            <bookmark parentId="1">another children bookmark</bookmark>
	        </behaviours>
	        Some another content
	    </div>
	    <div>
	        <behaviours>
	            <bookmark>another parent bookmark</bookmark>
	        </behaviours>
	       Some content
	    </div>
	</dynamic-page>
</pdf>

"bookmark" 行为的快捷方式是 "bookmark" 属性，如果您为此属性分配一些值，则引用此标签的书签将被自动创建。

父标签的书签也是子书签的父级。

示例

<pdf>
    <dynamic-page>
	    <div bookmark="parent bookmark">
	        Some content
	        <div bookmark="children bookmark">
	            Some another content
	        </div>
	        <div bookmark="another children bookmark">
	            Some another content
	        </div>
	    </div>
	    <div bookmark="another parent bookmark">
	       Some content
	    </div>
	</dynamic-page>
</pdf>

上面的结构（两个示例）将创建以下书签结构

  • 父书签
    • 子书签
    • 另一个子书签
  • 另一个父书签

粘贴笔记

可以使用 "note" 属性创建粘贴笔记。

示例

<pdf>
    <dynamic-page>
        <div note="note text"></div>
    </dynamic-page>
</pdf>

XML 解析器规范化属性值，这导致忽略换行符。

如果您想添加带有换行符的笔记，您应该使用此语法

<pdf>
    <dynamic-page>
        <div>
            <behaviours>
                <note>note text</note>
            </behaviours>
        </div>
    </dynamic-page>
</pdf>

重复的页眉和页脚

"占位符" 可以用于添加重复的页眉或/和页脚。

一些元素有特殊的 "占位符"：页面有页眉和页脚，表格也有页眉和页脚（待实现：尚未实现）等。

<pdf>
    <dynamic-page>
        <placeholders>
            <header>
                <div height="50px" width="100%">
                    Header
                </div>
            </header>
            <footer>
                <div height="50px" width="100%">
                    Footer
                </div>
            </footer>
        </placeholders>
    </dynamic-page>
</pdf>

页眉和页脚需要设置高度属性。此高度与页面顶部和底部边距合并。

工作区是页面大小减去页面边距和占位符（页脚和页眉）高度的结果。

水印

页面可以有一个 "watermark" 占位符。

水印可以设置在块和容器元素上，例如：div、p、h1（不包括span、纯文本或img）。

如果您想使用图像作为水印，应将img标签包裹在div中。

示例

<pdf>
    <dynamic-page>
        <placeholders>
            <watermark>
                <!-- rotate can have absolute values (45deg - in degrees, 0.123 - in radians) or relative values ("diagonally" and "-diagonally" - angle between diagonal and base side of the page) -->
                <div rotate="diagonally" alpha="0.1">
                    <img src="path/to/image.png" />
                </div>
            </watermark>
        </placeholders>
    </dynamic-page>
</pdf>

页码

有两种标签可以用于在页脚、页眉或水印中显示页信息：page-info和page-number。

此元素仅与动态页一起使用，不适用于单页。Page-info显示当前页码和总页码，page-number仅显示当前页码。

此标签的属性

  • format - 输出字符串的格式，该字符串将用作sprintf函数的参数。默认值：“%s.”用于page-number，“%s / %s”用于page-info。
  • offset - 将添加到当前页码和总页码的值。如果您想从非零值开始计数，则很有用。默认：0。

示例

<pdf>
    <dynamic-page>
        <placeholders>
            <header>
                <div height="20px">
                    <page-info format="page %s for %s" />

                    <!-- when we would like to number from 2 -->
                    <page-info offset="1" format="page %s for %s" />

                    <!-- when we would like to display only current page number -->
                    <page-info format="%1$s." />
                    <!-- or -->
                    <page-number />

                    <!-- when we would like to display only total pages number -->
                    <page-info format="%2$s pages" />
                </div>
            </header>
        </placeholders>
        Some text
    </dynamic-page>
</pdf>

使用PDF文档作为模板

“page”和“dynamic-page”标签可以有一个“document-template”属性，允许您使用外部PDF文档作为模板。

对于“page”标签，页的模板将是外部文档的第一页。

对于“dynamic-page”标签，每页的模板将是外部文档的对应页。

示例

<pdf>
    <dynamic-page document-template="path/to/file.pdf">
        <div>Some content</div>
    </dynamic-page>
</pdf>

列分页

页面可以按列分隔

<pdf>
    <dynamic-page>
        <column-layout>
            <div width="100%" height="2500px" background.color="green">
            </div>
        </column-layout>
    </dynamic-page>
</pdf>

上面的XML描述了PDF文档的几页，绿色矩形按两列分隔。

“column-layout”标签有三个附加参数：number-of-columns、margin-between-columns和equals-columns。

此属性的默认值分别为2、10和false。如果设置equals-columns属性，则列的高度将大致相等。

分割页面和列

可以通过以下标签手动分割页面和列：page-break、column-break、break。

所有这些标签都是相同的。这些标签必须是分割元素的直接子元素（dynamic-page或column-layout）。

如果您想在某些标签上避免自动页面或列断开，应将此标签的“breakable”属性设置为“off”。

示例

<pdf>
    <dynamic-page>
        <div breakable="false">this div won't be automatically broken</div>
    </dynamic-page>
</pdf>

元数据

可以通过在文档根处添加属性来添加元数据。

支持的元数据：Creator、Keywords、Subject、Author、Title、ModDate、CreationDate和Trapped。

** 这些属性名称是区分大小写的。 **

示例

<pdf Author="Piotr Sliwa" Title="Test document">
    <!-- some other elements -->
</pdf>

配置

库有四个主要的配置文件，允许您根据特定需求扩展库。

  • complex-attributes.xml - 复杂属性类声明的逻辑名称，用于识别整个库中的属性。
  • nodes.xml - XML文档中允许的标签的定义，包括默认属性和格式化对象。
  • fonts.xml - 字体定义，并分配给识别整个库中字体的逻辑名称。
  • colors.xml - 颜色定义调色板

为了更改默认的配置文件，您必须将配置好的Loader对象传递给Facade构造函数。

    $loader = new PHPPdf\Core\Configuration\LoaderImpl(
        '/path/to/file/nodes.xml',
        '/path/to/file/enhancements.xml',
        '/path/to/file/fonts.xml',
        '/path/to/file/colors.xml'
    );
    
    $facade = new PHPPdf\Core\Facade($loader);

如果您只想更改一个配置文件，应使用LoaderImpl::set*方法。

$loader = new PHPPdf\Core\Configuration\LoaderImpl();
$loader->setFontFile(
'/path/to/file/fonts.xml'); //there are setFontFile, setNodeFile, setComplexAttributeFile and setColorFile methods
$facade = new PHPPdf\Core\Facade($loader);

FacadeBuilder可用于构建和配置Facade。FacadeBuilder能够配置缓存、渲染引擎和文档解析器。

$builder = PHPPdf\Core\FacadeBuilder::create(/* you can pass specyfic configuration loader object */)
                                        ->setCache('File', array('cache_dir' => './cache'))
                                        ->setUseCacheForStylesheetConstraint(true); //stylesheets will be also use cache

$facade = $builder->build();

Markdown支持

库支持基本的（官方）markdown语法。要将markdown文档转换为pdf，您应通过MarkdownDocumentParser配置Facade对象。您也可以使用FacadeBuilder来执行此操作。

示例

$facade = PHPPdf\Core\FacadeBuilder::create()
                                   ->setDocumentParserType(PHPPdf\Core\FacadeBuilder::PARSER_MARKDOWN)
                                   ->setMarkdownStylesheetFilepath(/** optionaly path to stylesheet in xml format */)
                                   ->build();

默认情况下，在Markdown PDF文档中，使用Helvetica字体。如果您想使用UTF-8字符或自定义PDF文档，应通过使用FacadeBuilder::setMarkdownStylesheetFilepath方法提供自己的样式表。

样式表结构已在样式表章节中描述。默认情况下，样式表为空，如果您想设置另一种字体类型，样式表应如下所示

<stylesheet>
    <any font-type="DejaVuSans" />
</stylesheet>

内部，MarkdownDocumentParser将Markdown文档转换为HTML（通过PHP markdown库），然后转换为XML，最后转换为PDF文档。

请注意，如果您在Markdown文档中使用了与PHPPdf XML语法不兼容的原始HTML（例如不存在的属性或标签），解析器将抛出异常。

Not all tags used in the markdown implementation are propertly supported by PHPPdf, for example "pre" and "code" tags.
For now "pre" tag is an alias for "div", and "code" tag is an alias for "span", be aware of that.

图像生成引擎

PHPPdf能够生成图像（jpg或png）文件，而不是PDF文档。要实现这一点，您必须配置FacadeBuilder，例如

$facade = PHPPdf\Core\FacadeBuilder::create()
                                   ->setEngineType('image')
                                   ->build();

//render method returns array of images' sources, one pdf page is generated to single image file 
$images = $facade->render(...);

默认情况下使用GD库来渲染图像。

但您也可以使用Imagick，它提供更好的质量，因此如果您有机会在服务器上安装Imagick，则推荐使用它。要切换图形库，您必须使用setEngineOptions方法配置FacadeBuilder对象

$builder = ...;
$builder->setEngineOptions(array(
    'engine' => 'imagick',
    'format' => 'png',//png, jpeg or wbmp
    'quality' => 60,//int from 0 to 100
));

支持的图形库包括：GD（默认）、imagick、gmagick。PHPPdf使用Imagine库作为图形文件生成的接口。

已知限制

以下是当前版本库的已知限制列表

  • 无法将图像注入到具有浮动属性的文字中——将在下一个版本中引入
  • 对表格元素内的float属性的支持是局部的（在表格内浮动可能工作不正常）
  • 如果设置了此属性的元素中有多于一个元素，则vertical-align属性工作不正常
  • 边框不改变元素的尺寸（而在HTML中它们会改变）
  • png文件（尤其是没有压缩的）效率低下。应使用高压缩（压缩级别6或更高）的png文件或jpeg文件
  • 并非所有标签都得到适当支持，例如，“pre”标签是“div”的别名，“code”标签是“span”的别名
  • 线性标签（text、span、code、page-info、page-number、a、b、i、em）的嵌套没有得到适当支持。如果一个线性标签包含另一个，则只合并此标签内的文本，样式来自最外层的线性标签。

TODO - 计划

  • 自动生成“目录”
  • 改进表格、标题和页脚，对于表格的rowspan。当使用colspan时，修复单元格的最小高度计算。
  • 支持简单的柱状图和饼图

技术要求

此库与php 5.3及以上版本兼容。