README

Gotenberg PHP

用于与Gotenberg交互的PHP客户端

本包是Gotenberg的PHP客户端，一个友好的开发者API，用于与Chromium和LibreOffice等强大工具交互，将多种文档格式（HTML、Markdown、Word、Excel等）转换为PDF文件，还有更多！

⚠️

对于Gotenberg 6.x，请使用thecodingmachine/gotenberg-php-client。

对于Gotenberg 7.x，请使用版本v1.1.8。

快速示例

您可以将目标URL转换为PDF并保存到指定目录

use Gotenberg\Gotenberg;

// Converts a target URL to PDF and saves it to a given directory.
$filename = Gotenberg::save(
    Gotenberg::chromium($apiUrl)->pdf()->url('https://my.url'), 
    $pathToSavingDirectory
);

您还可以将Office文档合并

use Gotenberg\Gotenberg;
use Gotenberg\Stream;

// Converts Office documents to PDF and merges them.
$response = Gotenberg::send(
    Gotenberg::libreOffice($apiUrl)
        ->merge()
        ->convert(
            Stream::path($pathToDocx),
            Stream::path($pathToXlsx)
        )
);

需求

此包需要Gotenberg，一个由Docker驱动的无状态API，用于PDF文件。

有关更多信息，请参阅安装指南。

安装

您可以使用Composer安装此包

composer require gotenberg/gotenberg-php

我们使用PSR-7 HTTP消息接口（即RequestInterface和ResponseInterface）和PSR-18 HTTP客户端接口（即ClientInterface）。

对于后者，您可能需要一个适配器才能使用您喜欢的客户端库。请检查可用的适配器

https://docs.php-http.org/en/latest/clients.html

如果您不确定应该使用哪个适配器，可以考虑使用php-http/guzzle7-adapter

composer require php-http/guzzle7-adapter

向API发送请求

在创建HTTP请求（见下文）后，您有两个选项

从API获取响应并根据您的需求处理它。
将生成的文件保存到指定目录。

在以下示例中，我们假设Gotenberg API在http://localhost:3000可用。

获取响应

您可以使用任何能够处理PSR-7 RequestInterface的HTTP客户端调用API

use Gotenberg\Gotenberg;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->url('https://my.url');
    
$response = $client->sendRequest($request);

如果您有一个兼容PSR-18的HTTP客户端（见安装），您也可以使用Gotenberg::send

use Gotenberg\Gotenberg;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->url('https://my.url');

try {
    $response = Gotenberg::send($request);
    return $response;
} catch (GotenbergApiErrored $e) {
    // $e->getResponse();
}

此辅助函数将解析响应，如果它不是2xx，则会抛出异常。这对于您希望直接将响应返回给浏览器特别有用。

您还可以显式设置HTTP客户端

use Gotenberg\Gotenberg;

$response = Gotenberg::send($request, $client);

保存生成的文件

如果您有一个兼容PSR-18的HTTP客户端（见安装），您可以使用Gotenberg::save

use Gotenberg\Gotenberg;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->url('https://my.url');
    
$filename = Gotenberg::save($request, '/path/to/saving/directory');

它返回结果文件的名称。默认情况下，Gotenberg创建一个UUID文件名（例如，95cd9945-484f-4f89-8bdb-23dbdd0bdea9），具有.zip或.pdf文件扩展名。

您还可以显式设置HTTP客户端

use Gotenberg\Gotenberg;

$response = Gotenberg::save($request, $pathToSavingDirectory, $client);

文件名

您可以使用以下方式覆盖输出文件名

use Gotenberg\Gotenberg;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->outputFilename('my_file')
    ->url('https://my.url');

Gotenberg将自动添加正确的文件扩展名。

跟踪或请求ID

默认情况下，Gotenberg会在日志中创建一个UUID跟踪，用于标识请求。您可以通过以下方式覆盖其值：

use Gotenberg\Gotenberg;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->trace('debug')
    ->url('https://my.url');

它将使用您的值设置头部Gotenberg-Trace。您还可以覆盖默认的头部名称

use Gotenberg\Gotenberg;

$request = Gotenberg::chromium('http://localhost:3000')
    ->pdf()
    ->trace('debug', 'Request-Id')
    ->url('https://my.url');

请注意，它应该与Gotenberg的--api-trace-header属性定义的值相同。

Gotenberg的响应也将包含跟踪头部。在出现错误的情况下，Gotenberg::send和Gotenberg::save方法将抛出GotenbergApiErroed异常，该异常提供了以下方法来检索跟踪：

use Gotenberg\Exceptions\GotenbergApiErrored;
use Gotenberg\Gotenberg;

try {
    $response = Gotenberg::send(
        Gotenberg::chromium('http://localhost:3000')
            ->screenshot()
            ->url('https://my.url')
    );
} catch (GotenbergApiErrored $e) {
    $trace = $e->getGotenbergTrace();
    // Or if you override the header name:
    $trace = $e->getGotenbergTrace('Request-Id');
}

访问文档了解如何与Gotenberg交互🚀

gotenberg / gotenberg-php

维护者

详细信息