appotter/phppdf

PHP的PDF和图形文件生成库（结合名为`THSarabun`的泰文字体）

维护者

详细信息

github.com/appotter/PHPPdf

源代码

安装: 65

依赖者: 0

建议者: 0

安全: 0

星标: 1

关注者: 1

分支: 0

1.0.0 2014-06-26 04:31 UTC

Requires

Suggests

MIT bbb1fb26a526fd1e87c0f345e8cdfe21d9ad77f7

pdfPHPPdfThai PHPPdf

This package is not auto-updated.

Last update: 2024-09-14 15:37:27 UTC

README

Build Status

示例

示例文档位于"examples"目录中。"index.php"文件是浏览示例的Web界面，"cli.php"是控制台界面。通过Web界面，文档可用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文件中的"minimum-stability"，并将其设置为dev。

"minimum-stability": "dev"

如果您不想使用composer，请按照以下说明手动安装此库及其所有依赖项。

此库使用以下外部依赖项

  • php-markdown
  • ZendPdf
  • Zend_Memory (Zend Framework 2.0.x版本)
  • Zend_Cache (Zend Framework 2.0.x版本)
  • Zend_Stdlib (Zend Framework 2.0.x版本)
  • Zend_EventManager (Zend Framework 2.0.x版本)
  • Zend_ServiceManager (Zend Framework 2.0.x版本)
  • Zend_Barcode (Zend Framework 2.0.x版本)
  • Imagine

为了使用此库，您必须下载所有这些依赖项。

从库的主目录执行以下命令（请确保已安装Git）

    php vendors.php

或者，您可以手动下载依赖项并将其复制到"lib/vendor"目录中。

默认情况下，vendors.php文件将下载整个ZF2存储库，但请记住，仅需要ZendPdf、Zend_Memory、Zend_Cache、Zend_Stdlib、Zend_ServiceManager和Zend_EventManager。为了启用条形码支持，必须安装Zend_Barcode。其他包和文件可以删除。

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" />
        </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
  • 美国尺寸：legal和letter

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

示例

    <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”标签。HTML的“style”属性在PHPPdf XML方言中不存在。

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

继承

与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 - 单页，具有固定大小
  • elastic-page - 单页，高度根据其子元素自动调整，类似于其他标签（例如 "div"）。页眉、页脚、水印、template-document属性不适用于此标签。特别适用于图形文件生成（图像引擎）。
  • page-break, column-break, break - 分页或列断开，此标签必须是 "dynamic-page" 或 "column-layout" 的直接子标签！
  • column-layout - 列上的独立工作空间，附加属性：number-of-columns（列数）、margin-between-columns（列间距）、equals-columns（等宽列）
  • barcode - 更多信息请参阅条形码章节
  • circle - 边框和背景为圆形的元素。附加属性：radius（它覆盖width和height属性）
  • pie-chart - 可以用来绘制简单饼图的元素（更多信息请参阅图表章节）。

有一些标签仅用于属性，一组标签等

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

属性

  • width和height：严格设置高度和宽度，支持的单位在单独的部分中描述。支持相对值，以百分比表示。
  • max-width, max-height：设置元素的最大尺寸
  • margin（margin-top, margin-bottom, margin-left, margin-right）：类似于HTML/CSS中的margin。简化元素的边距会合并。对于侧边距，可能的值为 "auto"，它在HTML/CSS中工作方式类似。
  • padding（padding-top, padding-bottom, padding-left, padding-right）：与HTML/CSS中的工作方式相似
  • font-type - 字体名称必须在fonts.xml配置文件中出现，否则将抛出异常
  • font-size - 以点为单位的文件大小，没有任何单位
  • font-style - 允许的值：normal, bold, italic, bold-italic
  • color - 文本颜色。支持HTML/CSS风格值
  • breakable - 如果为true，则元素能够被分成几个页面。大多数标签的默认值是true...
  • float - 与 HTML/CSS 中的用法相似，但不同。允许的值：left|none|right，默认值为 none
  • line-height - 与 HTML/CSS 中的用法相似。默认值：1.2*font-size
  • text-align - 与 HTML/CSS 中的用法相同。允许的值：left|center|right|justify，默认值为 left。
  • text-decoration - 允许的值：none, underline, overline, line-through
  • break - 在此属性所属元素的末尾断开页面或列。此属性的所属者必须是 dynamic-page 或 column-layout 标签的直接子元素！
  • colspan, rowspan - 与 HTML 中的用法相似（TODO：rowspan 尚未实现）
  • href - 元素应链接的外部 URL
  • ref - 应链接的元素 id
  • bookmark - 创建与给定标题相关联的标签书签
  • note - 创建与标签相关联的粘性便签
  • 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 和 right - 与 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: 仅由页面（或 dynamic-page）使用的属性。对于填充也使用边距，则为 true，否则为 false。
    • image-width: 背景图像的自定义宽度，允许使用百分比值
    • image-height: 背景图像的自定义高度，允许使用百分比值
    • position-x: 背景图像的水平位置，允许的值：left，center，right 或数值（默认：left）
    • position-y: 背景图像的垂直位置，允许的值：top，center，bottom 或数值（默认：top）

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

您可以通过使用“样式表”标签而不是简写来实现这一点。

    <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选项

您可以在＜a href="http://framework.zend.com/manual/en/zend.barcode.objects.html" rel="nofollow noindex noopener external ugc"＞Zend\Barcode文档＜/a＞中找到这些选项及其默认值。

为了渲染文本条形码，您不能使用以下嵌入的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>

重复的页眉和页脚

可以使用“placeholders”来添加重复的页眉或页脚。

某些元素有特殊的“placeholders”：页面有页眉和页脚，表格也有页眉和页脚（待实现）等。

    <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>

页眉和页脚需要设置一个高度属性。这个高度与页面的顶部和底部边距相加。

工作空间是减去页面边距和页眉、页脚高度后的页面大小。

水印

页面可以有一个“水印”占位符。

水印可以设置在块元素和容器元素上，例如：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。

此元素仅与dynamic-page配合使用，不适用于单页。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文档中使用原始HTML，它可能与PHPPdf的XML语法不兼容（例如不存在的属性或标签），解析器将抛出异常。

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属性的局部支持（在表格内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及以上版本兼容。