包简介

A PHP client for interacting with Gotenberg, a developer-friendly API for converting numerous document formats into PDF files, and more!

README 文档

README

Gotenberg PHP

A PHP client for interacting with Gotenberg

This package is a PHP client for Gotenberg, a developer-friendly API to interact with powerful tools like Chromium and LibreOffice for converting numerous document formats (HTML, Markdown, Word, Excel, etc.) into PDF files, and more!

Gotenberg version	Client
`8.x` (current)	`v2.x` (current)
`7.x`	`v1.x`
`6.x`	thecodingmachine/gotenberg-php-client

Tip

A Symfony Bundle is also available!

Quick Examples

You may convert a target URL to PDF and save it to a given directory:

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

You may also convert Office documents:

use Gotenberg\Gotenberg;
use Gotenberg\Stream;

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

Requirement

This packages requires Gotenberg, a containerized API for seamless PDF conversion.

See the installation guide for more information.

Installation

This package can be installed with Composer:

composer require gotenberg/gotenberg-php

We use PSR-7 HTTP message interfaces (i.e., RequestInterface and ResponseInterface) and the PSR-18 HTTP client interface (i.e., ClientInterface).

For the latter, you may need an adapter in order to use your favorite client library. Check the available adapters:

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

If you're not sure which adapter you should use, consider using the php-http/guzzle7-adapter:

composer require php-http/guzzle7-adapter

Build a request

This package is organized around modules, namely:

use Gotenberg\Gotenberg;

Gotenberg::chromium($apiUrl);
Gotenberg::libreOffice($apiUrl);
Gotenberg::pdfEngines($apiUrl);

Each of these modules offers a variety of methods to populate a multipart/form-data request.

After setting all optional form fields and files, you can create a request by calling the method that represents the endpoint. For example, to call the /forms/chromium/convert/url route:

use Gotenberg\Gotenberg;

Gotenberg::chromium($apiUrl)
    ->pdf()                  // Or screenshot().
    ->singlePage()           // Optional.
    ->url('https://my.url'));

Tip

Head to the documentation to learn about all possibilities.

If the route requires form files, use the Stream class to create them:

use Gotenberg\DownloadFrom;
use Gotenberg\Gotenberg;
use Gotenberg\Stream;

Gotenberg::libreOffice($apiUrl)
    ->convert(Stream::path($pathToDocument));

// Alternatively, you may also set the content directly.
Gotenberg::chromium($apiUrl)
    ->pdf()
    ->assets(Stream::string('style.css', 'body{font-family: Arial, Helvetica, sans-serif;}'))
    ->html(Stream::string('index.html', '<html><head><link rel="stylesheet" type="text/css" href="style.css"></head><body><p>Hello, world!</p></body></html>'));

// Or create your stream from scratch.
Gotenberg::libreOffice($apiUrl)
    ->convert(new Stream('document.docx', $stream));

// Or even tell Gotenberg to download the files for you.
Gotenberg::libreOffice($apiUrl)
    ->downloadFrom([
        new DownloadFrom('https://url.to.document.docx', ['MyHeader' => 'MyValue'])
    ])
    ->convert();

Send a request to the API

After having created the HTTP request, you have two options:

Get the response from the API and handle it according to your need.
Save the resulting file to a given directory.

Get a response

You may use any HTTP client that is able to handle a PSR-7 RequestInterface to call the API:

use Gotenberg\Gotenberg;

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

$response = $client->sendRequest($request);

If you have a PSR-18 compatible HTTP client (see Installation), you may also use Gotenberg::send:

use Gotenberg\Gotenberg;

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

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

This helper will parse the response and if it is not 2xx, it will throw an exception. That's especially useful if you wish to return the response directly to the browser.

You may also explicitly set the HTTP client:

use Gotenberg\Gotenberg;

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

Save the resulting file

If you have a PSR-18 compatible HTTP client (see Installation), you may use Gotenberg::save:

use Gotenberg\Gotenberg;

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

It returns the filename of the resulting file. By default, Gotenberg creates a UUID filename (i.e., 95cd9945-484f-4f89-8bdb-23dbdd0bdea9) with either a .zip or a .pdf file extension (or image formats for screenshots).

You may also explicitly set the HTTP client:

use Gotenberg\Gotenberg;

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

Filename

You may override the output filename with:

use Gotenberg\Gotenberg;

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

Gotenberg will automatically add the correct file extension.

Correlation ID

By default, Gotenberg creates a UUID correlation ID that identifies a request in its logs. You may override its value thanks to:

use Gotenberg\Gotenberg;

$request = Gotenberg::chromium($apiUrl)
    ->pdf()
    ->correlationId('debug')
    ->url('https://my.url');

It will set the header Gotenberg-Trace with your value. You may also override the default header name:

use Gotenberg\Gotenberg;

$request = Gotenberg::chromium($apiUrl)
    ->pdf()
    ->correlationId('debug', 'Request-Id')
    ->url('https://my.url');

Please note that it should be the same value as defined by the --api-correlation-id-header Gotenberg's property.

The response from Gotenberg will also contain the correlation ID header. In case of error, both the Gotenberg::send and Gotenberg::save methods throw a GotenbergApiErrored exception that provides the following method for retrieving it:

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

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

Note

The trace() and getGotenbergTrace() methods are deprecated but still available for backward compatibility.

gotenberg/gotenberg-php 适用场景与选型建议

gotenberg/gotenberg-php 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 6M 次下载、GitHub Stars 达 384，最近一次更新时间为 2021 年 11 月 28 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「excel」「xlsx」「csv」「markdown」「word」「pdf」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 gotenberg/gotenberg-php 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 gotenberg/gotenberg-php 我们能提供哪些服务？

定制开发 / 二次开发

基于 gotenberg/gotenberg-php 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 gotenberg/gotenberg-php 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

erelke/twig-spreadsheet-bundle 2

This Symfony bundle integrates PhpSpreadsheet into Symfony using Twig.

ideea/phpexcel 0

PHPExcel - OpenXML - Read, Create and Write Spreadsheet documents in PHP - Spreadsheet engine

ffsoft/export 0

Yii2 export extension

ahead4/php-excel 0

PHP Excel Library

jdefez/laravel-csv 0

laravel facade to read/write csv file

sqginfo/phpexcel 0