endroid/pdf

Endroid PDF

资助包维护!
endroid

1.5.4 2023-11-07 08:54 UTC

README

endroid 提供

Latest Stable Version Build Status Total Downloads License

基于 wkhtmltopdf 和 Snappy 的简单 PDF 生成库。点击 此处 查看示例。请注意,此示例包含大量页面,加载可能需要一些时间,并且未应用缓存。

阅读 博客 了解更多关于创建此库的原因和使用方法的信息。

轻松加载数据

当你生成 PDF 时,你需要确保将正确的内容传递给 PDF 对象。这些数据可以来自任何来源(文件、URL、控制器),其中一些会对性能产生影响,因此你通常希望缓存这些内容,而不是每次生成 PDF 时都加载数据。

endroid/asset 通过允许你通过简单的选项数组定义你的资产来减轻这种负担。资产工厂和猜测器确保创建正确的资产类型,并提供所谓的缓存资产,它包装了任何其他资产。

$this->pdfBuilder
    ->setCover([
        'controller' => CoverController::class,
        'parameters' => ['title' => 'My PDF', 'date' => new DateTime()],
        'cache_key' => 'cover',
        'cache_expires_after' => 3600,
        'cache_clear' => true, // use to purge any previously cached data
    ])
;

有关更多信息,请 阅读文档

处理外部资源

一个 HTML 页面可以包含许多外部资源,每个都会触发一个单独的请求。然而,在生成 PDF 时,这可能会导致性能或甚至稳定性问题。因此,我们需要将请求的数量降到最低。

endroid/embed 库通过允许你通过 Twig 扩展嵌入外部资源来帮助你最小化 PDF 生成期间需要加载的资产数量。你可以使用此扩展来嵌入字体、样式表和脚本等资源。

<link rel="stylesheet" href="{{ embed(asset('/styles.css')) }}">

<style>
@font-face {
    font-family: 'SCP';
    font-weight: normal;
    src: url('{{ embed('https://fontlibrary.org/scp.ttf') }}');
}
</style>

有关更多信息,请 阅读文档

PDF 构建器

endroid/installer 检测到 Symfony 时,构建器将自动连接,你可以立即开始使用它来构建 PDF。这是你可以如何使用构建器的一个示例。

$pdfBuilder
    ->setCover([
        'controller' => CoverController::class,
        'cache_key' => 'cover',
        'cache_expires_after' => 3600,
    ])
    ->setTableOfContents([
        'path' => '/var/www/html/table_of_contents.xml',
        'cache_key' => 'toc',
    ])
    ->setHeader([
        'template' => 'pdf/header.html.twig',
        'cache_key' => 'header',
    ])
    ->setFooter([
        'template' => 'pdf/footer.html.twig',
        'cache_key' => 'footer',
    ])
    ->setContent([
        'url' => 'http://endroid.nl/',
        'cache_key' => 'content',
    ])
    ->setOptions([
        'margin-top' => 16,
        'margin-bottom' => 16,
        'header-spacing' => 5,
        'footer-spacing' => 5,
    ])
;

$pdf = $pdfBuilder->getPdf();

// Create a response object
$response = InlinePdfResponse::createFromPdf($pdf);

// Or output directly
header('Content-type: application/pdf');
echo $pdf->generate();

安装

使用 Composer 安装库。

$ composer require endroid/pdf

Symfony

当你使用 Symfony 时,installer 会确保服务自动连接。如果 Snappy\Pdf 服务尚未注册,请确保为它创建一个服务定义或安装 knplabs/snappy-bundle 以及库。

$ composer require endroid/pdf knplabs/knp-snappy-bundle

此外,如果任何资产类型不受支持(例如,因为你没有缓存组件或 Twig)或者你只是不想注册某些类型,你可以通过服务配置取消注释适配器。

启动 PDF 构建器

当没有自动连接可用时,你需要自己实例化和连接必要的依赖项。你可以通过启动文件等方式这样做。

$snappy = new Snappy(__DIR__.'/../vendor/h4cc/wkhtmltopdf-amd64/bin/wkhtmltopdf-amd64');

$assetFactory = new AssetFactory();
$assetFactory->add(new DataAssetFactoryAdapter());
$assetFactory->add(new ControllerAssetFactoryAdapter($kernel, $requestStack));
$assetFactory->add(new TemplateAssetFactoryAdapter($twig));
...

$pdfBuilder = new PdfBuilder(new Pdf($snappy), $assetFactory);

版本控制

版本号遵循 MAJOR.MINOR.PATCH 体系结构。向后兼容的更改将保持在最低限度,但请注意,这些可能会发生。在生产中锁定依赖关系,并在升级时测试您的代码。

许可

本软件包采用MIT许可协议。有关完整的版权和许可信息,请查看随源代码一同分发的LICENSE文件。