README

snappdf

一个简单的库，允许您使用Chromium浏览器将网页或HTML转换为PDF文件。

• snappdf
  • 用法
    • 命令行用法
  • 速度
  • 要求
  • 安装
    • 下载本地Chromium
    • 跳过Chromium下载
    • 无头Chrome在UNIX上无法启动
    • 与Browsershot的比较
    • 延迟加载
    • 临时文件
  • 鸣谢
  • 许可证

用法

以下是一个快速示例，说明它是如何工作的

$snappdf = new \Beganovich\Snappdf\Snappdf();

$pdf = $snappdf
    ->setHtml('<h1>Hello world!</h1>')
    ->save('/path/to/your/file.pdf');

如果您想将网页转换为PDF，可以使用setUrl()而不是setHtml()

$snappdf = new \Beganovich\Snappdf\Snappdf();

$pdf = $snappdf
    ->setUrl('https://github.com')
    ->save('/path/to/your/file.pdf');

..如果您需要特定版本的Chrome，或者不想使用本地下载的Chromium，可以使用setChromiumPath方法。

$snappdf = new \Beganovich\Snappdf\Snappdf();

$pdf = $snappdf
    ->setUrl('https://github.com')
    ->setChromiumPath('/path/to/your/chrome')
    ->save('/path/to/your/file.pdf');

使用blade模板的Laravel用法

$snappdf = new \Beganovich\Snappdf\Snappdf();

$fields = [...];

// Render method returns HTML string (template compile)
$html = view('pdf.warranty', compact('fields'))->render();

$pdf = $snappdf
    ->setHtml($html)
    ->save('/path/to/your/file.pdf');

如果您之前列出的任何选项都不符合您的需求，您也可以使用环境变量设置Chromium的可执行文件路径。

SNAPPDF_EXECUTABLE_PATH=/path/to/your/chrome

这是Nginx配置（服务器块）的示例（感谢@cdahinten）

fastcgi_param SNAPPDF_EXECUTABLE_PATH '/usr/bin/chromium';
fastcgi_param SNAPPDF_SKIP_DOWNLOAD true;

如果您只需要生成PDF而不保存，请使用generate()

$snappdf = new \Beganovich\Snappdf\Snappdf();

$pdf = $snappdf
    ->setUrl('https://github.com')
    ->setChromiumPath('/path/to/your/chrome')
    ->generate();

file_put_contents('my.pdf', $pdf); // for local storage

Storage::disk('s3')->put('my.pdf', $pdf); // for remote storage

注意：setChromiumPath具有最高优先级。其次是环境变量，然后是本地下载。

尽管默认参数在大多数情况下应该有效，但您可以指定要使用的参数。

使用addChromiumArguments方法

$snappdf = new \Beganovich\Snappdf\Snappdf();

$pdf = $snappdf
    ->setUrl('https://github.com')
    ->setChromiumPath('/path/to/your/chrome')
    ->addChromiumArguments('--single-process --tls1')
    ->generate();

如果您想删除单个参数，可以使用clearChromiumArgument。

$snappdf = new \Beganovich\Snappdf\Snappdf();

$snappdf->getChromiumArguments(); // ['--headless', '--disable-gpu', '--disable-translations']
$snappdf->clearChromiumArgument('--headless'); // ['--disable-gpu', '--disable-translations']

如果您想覆盖默认参数，可以使用SNAPPDF_EXECUTABLE_ARGUMENTS环境变量。

注意：始终添加--print-to-pdf参数，并且每次调用waitBeforePrinting方法时都会添加--virtual-time-budget参数。

要清除所有参数，可以使用clearChromiumArguments方法。

$snappdf = new \Beganovich\Snappdf\Snappdf();

// $snappdf->getChromiumArguments() = [ '--headless', '--disable-gpu', ... ]

$snappdf->setChromiumPath('/path/to/your/chrome')
    ->clearChromiumArguments();

// $snappdf->getChromiumArguments() = []

命令行用法

如果您想将snappdf作为命令行工具使用，请使用“convert”命令

./vendor/bin/snappdf convert --url https://github.com /path/to/save.pdf

如果您想转换HTML

./vendor/bin/snappdf convert --html "<h1>Hello world!</h1>" /path/to/save.pdf

您还可以指定自定义二进制位置（如果您不使用本地下载的Chromium修订版）

./vendor/bin/snappdf convert --url https://github.com --binary /usr/bin/google-chrome /path/to/save.pdf

速度

此库的主要优点和存在的原因是生成PDF的速度。它直接与浏览器本身通信，生成PDF的时间不到0.5秒（冷启动）。这在配备i5-5300U和平均SSD的中端笔记本电脑上进行了测试。

➜  snappdf git:(master) ./vendor/bin/phpunit --testdox --filter=testGeneratingPdfWorks
PHPUnit 9.5.0 by Sebastian Bergmann and contributors.

Snappdf (Test\Snappdf\Snappdf)
 ✔ Generating pdf works

Time: 00:00.199, Memory: 6.00 MB

OK (1 test, 1 assertion)
➜  snappdf git:(master) ./vendor/bin/phpunit --testdox --filter=testGeneratingPdfWorks
PHPUnit 9.5.0 by Sebastian Bergmann and contributors.

Snappdf (Test\Snappdf\Snappdf)
 ✔ Generating pdf works

Time: 00:00.171, Memory: 6.00 MB

OK (1 test, 1 assertion)

要求

• PHP 8

安装

Composer是安装库的推荐方式

composer require beganovich/snappdf

下载本地Chromium

snappdf可以下载并使用本地Chromium修订版。要实现这一点，可以使用

./vendor/bin/snappdf download

您可以在%projectRoot%/vendor/beganovich/snappdf/versions中找到本地下载/修订版。

只有在您没有使用setChromiumPath()提供路径的情况下，才会使用本地修订版。

注意：snappdf将下载并使用Chromium的最新构建版本。由于Chromium本身没有稳定或不稳定版本，浏览器本身可能存在错误或可能损坏。我们不对此承担责任。如果您将安全和稳定性放在首位，请安装Google Chrome稳定版本并将包指向使用该版本。

跳过Chromium下载

如果您需要动态跳过下载，请使用SNAPPDF_SKIP_DOWNLOAD环境变量。

无头Chrome在UNIX上无法启动

确保您的系统已安装所有必需的依赖项。感谢Puppeteer ❤

ca-certificates
fonts-liberation
libappindicator3-1
libasound2
libatk-bridge2.0-0
libatk1.0-0
libc6
libcairo2
libcups2
libdbus-1-3
libexpat1
libfontconfig1
libgbm1
libgcc1
libglib2.0-0
libgtk-3-0
libnspr4
libnss3
libpango-1.0-0
libpangocairo-1.0-0
libstdc++6
libx11-6
libx11-xcb1
libxcb1
libxcomposite1
libxcursor1
libxdamage1
libxext6
libxfixes3
libxi6
libxrandr2
libxrender1
libxss1
libxtst6
lsb-release
wget
xdg-utils

Note: You might need to install ‘libgbm-dev’ and ‘libxshmfence-dev’ also. This is reported for Ubuntu 20.04.

alsa-lib.x86_64
atk.x86_64
cups-libs.x86_64
gtk3.x86_64
ipa-gothic-fonts
libXcomposite.x86_64
libXcursor.x86_64
libXdamage.x86_64
libXext.x86_64
libXi.x86_64
libXrandr.x86_64
libXScrnSaver.x86_64
libXtst.x86_64
pango.x86_64
xorg-x11-fonts-100dpi
xorg-x11-fonts-75dpi
xorg-x11-fonts-cyrillic
xorg-x11-fonts-misc
xorg-x11-fonts-Type1
xorg-x11-utils

yum update nss -y

与Browsershot的比较

如果您需要更复杂的软件来执行与无头浏览器相关的操作，请使用 Spatie 的 Browsershot。这是一个出色的软件包。snappdf 的目的是尽可能简洁，并仅关注生成 PDF。

此外，snappdf 运行不需要安装 Node。

延迟加载

您可以使用 waitBeforePrinting() 设置在运行打印之前的最大延迟。此用法可能是在您需要发出 Ajax 调用或等待库（例如图表）加载后再进行打印的情况下。

注意：提供的值以毫秒为单位。一个非常重要的提示是：如果您延迟加载 10 秒（10000 毫秒），这不会使 PDF 渲染本身延迟 10 秒，但会为库或 Ajax 调用完成提供时间，然后执行打印操作。

简而言之；如果您将延迟加载设置为 10 秒，而 Ajax 调用需要 2 秒才能完成，PDF 渲染将在 Ajax 调用完成后立即开始（2 秒后），而不会等待 10 秒。

临时文件

从版本 3 开始，snappdf 将自动删除临时文件。如果您仍然希望保留它们，您可以使用 setKeepTemporaryFiles 方法。

$snappdf = new \Beganovich\Snappdf\Snappdf();

$pdf = $snappdf
    ->setUrl('https://github.com')
    ->setChromiumPath('/path/to/your/chrome')
    ->setKeepTemporaryFiles(true)
    ->generate();

file_put_contents('my.pdf', $pdf);

鸣谢

• David Bomba
• Benjamin Beganović
• 所有贡献者

许可证

MIT 许可证（MIT）。