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!
For Gotenberg 6.x, use thecodingmachine/gotenberg-php-client instead.
For Gotenberg 7.x, use version v1.1.8
.
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 and merge them:
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)
)
);
This packages requires Gotenberg, a Docker-powered stateless API for PDF files.
See the installation guide for more information.
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:
If you're not sure which adapter you should use, consider using the php-http/guzzle7-adapter
:
composer require php-http/guzzle7-adapter
After having created the HTTP request (see below), 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.
In the following examples, we assume the Gotenberg API is available at http://localhost:3000.
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('http://localhost:3000')
->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('http://localhost:3000')
->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);
If you have a PSR-18 compatible HTTP client (see Installation), you may use Gotenberg::save
:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium('http://localhost:3000')
->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.
You may also explicitly set the HTTP client:
use Gotenberg\Gotenberg;
$response = Gotenberg::save($request, $pathToSavingDirectory, $client);
You may override the output filename with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium('http://localhost:3000')
->pdf()
->outputFilename('my_file')
->url('https://my.url');
Gotenberg will automatically add the correct file extension.
By default, Gotenberg creates a UUID trace that identifies a request in its logs. You may override its value thanks to:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium('http://localhost:3000')
->pdf()
->trace('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('http://localhost:3000')
->pdf()
->trace('debug', 'Request-Id')
->url('https://my.url');
Please note that it should be the same value as defined by the --api-trace-header
Gotenberg's property.
The response from Gotenberg will also contain the trace header. In case of error, both the Gotenberg::send
and
Gotenberg::save
methods throw a GotenbergApiErroed
exception that provides the following method for retrieving the
trace:
use Gotenberg\Exceptions\GotenbergApiErrored;
use Gotenberg\Gotenberg;
try {
$response = Gotenberg::send(
Gotenberg::chromium('http://localhost:3000')
->pdf()
->url('https://my.url')
);
} catch (GotenbergApiErrored $e) {
$trace = $e->getGotenbergTrace();
// Or if you override the header name:
$trace = $e->getGotenbergTrace('Request-Id');
}
The Chromium module interacts with the Chromium browser to convert HTML documents to PDF or capture screenshots.
See https://gotenberg.dev/docs/routes#url-into-pdf-route.
Converting a target URL to PDF is as simple as:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->url('https://my.url');
See https://gotenberg.dev/docs/routes#html-file-into-pdf-route.
You may convert an HTML document with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->html(Stream::path('/path/to/file.html'));
Or with an HTML string:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->html(Stream::string('my.html', $someHtml));
Please note that it automatically sets the filename to index.html
, as required by Gotenberg, whatever the value you're
using with the Stream
class.
You may also send additional files, like images, fonts, stylesheets, and so on. The only requirement is that their paths in the HTML DOM are on the root level.
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->assets(
Stream::path('/path/to/my.css'),
Stream::path('/path/to/my.js')
)
->html(Stream::path('/path/to/file.html'));
See https://gotenberg.dev/docs/routes#markdown-files-into-pdf-route.
You may convert markdown files with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->markdown(
Stream::path('/path/to/my_wrapper.html'),
Stream::path('/path/to/file.md')
);
The first argument is a Stream
with HTML content, for instance:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My PDF</title>
</head>
<body>
{{ toHTML "file.md" }}
</body>
</html>
Here, there is a Go template function toHTML
. Gotenberg will use it to convert a markdown file's content to HTML.
Like the HTML conversion, you may also send additional files, like images, fonts, stylesheets, and so on. The only requirement is that their paths in the HTML DOM are on the root level.
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->assets(
Stream::path('/path/to/my.css'),
Stream::path('/path/to/my.js')
)
->markdown(
Stream::path('/path/to/file.html'),
Stream::path('/path/to/my.md'),
Stream::path('/path/to/my2.md')
);
You may print the entire content in one single page with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->singlePage()
->url('https://my.url');
You may override the default paper size with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->paperSize($width, $height)
->url('https://my.url');
Examples of paper size (width x height, in inches):
Letter
- 8.5 x 11 (default)Legal
- 8.5 x 14Tabloid
- 11 x 17Ledger
- 17 x 11A0
- 33.1 x 46.8A1
- 23.4 x 33.1A2
- 16.54 x 23.4A3
- 11.7 x 16.54A4
- 8.27 x 11.7A5
- 5.83 x 8.27A6
- 4.13 x 5.83
You may override the default margins (i.e., 0.39
):
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->margins($top, $bottom, $left, $right)
->url('https://my.url');
You may force page size as defined by CSS:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->preferCssPageSize()
->url('https://my.url');
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->printBackground()
->url('https://my.url');
You may also hide the default white background and allow generating PDFs with transparency with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->printBackground()
->omitBackground()
->url('https://my.url');
The rules regarding the printBackground
and omitBackground
form fields are the following:
- If
printBackground
is set to false, no background is printed. - If
printBackground
is set to true:- If the HTML document has a background, that background is used.
- If not:
- If
omitBackground
is set to true, the default background is transparent. - If not, the default white background is used.
- If
You may override the default portrait orientation with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->landscape()
->url('https://my.url');
You may override the default scale of the page rendering (i.e., 1.0
) with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->scale(2.0)
->url('https://my.url');
You may set the page ranges to print, e.g., 1-5, 8, 11-13
. Empty means all pages.
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->nativePageRanges('1-2')
->url('https://my.url');
You may add a header and/or a footer to each page of the PDF:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->header(Stream::path('/path/to/my_header.html'))
->footer(Stream::path('/path/to/my_footer.html'))
->url('https://my.url');
Please note that it automatically sets the filenames to header.html
and footer.html
, as required by Gotenberg,
whatever the value you're using with the Stream
class.
When the page relies on JavaScript for rendering, and you don't have access to the page's code, you may want to wait a
certain amount of time (i.e., 1s
, 2ms
, etc.) to make sure Chromium has fully rendered the page you're trying to generate.
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->waitDelay('3s')
->url('https://my.url');
You may also wait until a given JavaScript expression returns true:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->waitForExpression("window.globalVar === 'ready'")
->url('https://my.url');
Some websites have dedicated CSS rules for print. Using screen
allows you to force the "standard" CSS rules:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->emulateScreenMediaType()
->url('https://my.url');
You may also force the print
media type with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->emulatePrintMediaType()
->url('https://my.url');
You may add ccookies to store in the Chromium cookie jar:
use Gotenberg\Modules\ChromiumCookie;
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->cookies([
new ChromiumCookie(name: 'yummy_cookie', value: 'choco', domain: 'theyummycookie.com'),
new ChromiumCookie(name: 'vanilla_cookie', value: 'vanilla', domain: 'theyummycookie.com', path: '/', secure: true, httpOnly: true, sameSite: 'Lax'),
])
->url('https://my.url');
You may overridethe default User-Agent HTTP header with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->userAgent('Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)')
->url('https://my.url');
You may add HTTP headers that Chromium will send when loading the HTML document:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->extraHttpHeaders([
'My-Header-1' => 'My value',
'My-Header-2' => 'My value'
])
->url('https://my.url');
You may force Gotenberg to return a 409 Conflict
response if the HTTP status code from the main page is not acceptable:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->failOnHttpStatusCodes([499])
->url('https://my.url');
A X99
entry means every HTTP status codes between X00
and X99
(e.g., 499 means every HTTP status codes between 400 and 499).
You may force Gotenberg to return a 409 Conflict
response if there are exceptions in the Chromium console:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->failOnConsoleExceptions()
->url('https://my.url');
Gotenberg, by default, waits for the network idle event to ensure that the majority of the page is rendered during
conversion. However, this often significantly slows down the conversion process. Setting skipNetworkEventIdle
form
field to true can greatly enhance the conversion speed.
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->skipNetworkIdleEvent()
->url('https://my.url');
See https://gotenberg.dev/docs/routes#pdfa-chromium.
You may set the PDF/A format and enable PDF/UA for the resulting PDF with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->pdfFormat('PDF/A-1a')
->pdfua()
->url('https://my.url');
See https://gotenberg.dev/docs/routes#metadata-chromium.
You may set the metadata to write with:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->pdf()
->metadata(['Producer' => 'Gotenberg'])
->url('https://my.url');
You can capture screenshots using the following three routes, which function similarly to their PDF equivalents:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->screenshot()
->width(1280)
->height(800)
->clip()
->png()
->optimizeForSpeed()
->url('https://my.url');
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::chromium($apiUrl)
->screenshot()
->jpeg()
->quality(50)
->assets(
Stream::path('/path/to/my.css'),
Stream::path('/path/to/my.js')
)
->html(Stream::path('/path/to/file.html'));
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::chromium($apiUrl)
->screenshot()
->webp()
->markdown(
Stream::path('/path/to/my_wrapper.html'),
Stream::path('/path/to/file.md')
);
The LibreOffice module interacts with LibreOffice to convert documents to PDF, thanks to unoconv.
See https://gotenberg.dev/docs/routes#office-documents-into-pdfs-route.
Converting a document to PDF is as simple as:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->convert(Stream::path('/path/to/my.docx'));
If you send many documents, Gotenberg will return a ZIP archive with the PDFs:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->outputFilename('archive')
->convert(
Stream::path('/path/to/my.docx'),
Stream::path('/path/to/my.xlsx')
);
// $filename = archive.zip
$filename = Gotenberg::save($request, $pathToSavingDirectory);
You may also merge them into one unique PDF:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->merge()
->outputFilename('merged')
->convert(
Stream::path('/path/to/my.docx'),
Stream::path('/path/to/my.xlsx')
);
// $filename = merged.pdf
$filename = Gotenberg::save($request, $pathToSavingDirectory);
Please note that the merging order is determined by the order of the arguments.
You may override the default portrait orientation with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->landscape()
->convert(Stream::path('/path/to/my.docx'));
You may set the page ranges to print, e.g., 1-4
. Empty means all pages.
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->nativePageRanges('1-2')
->convert(Stream::path('/path/to/my.docx'));
You may set whether to export the form fields or to use the inputted/selected content of the fields:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->exportFormFields(false)
->convert(Stream::path('/path/to/my.docx'));
You may set whether to render the entire spreadsheet as a single page:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->singlePageSheets()
->convert(Stream::path('/path/to/my.xlsx'));
You may tweak image conversion performance with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->losslessImageCompression()
->reduceImageResolution(false)
->convert(Stream::path('/path/to/my.docx'));
See https://gotenberg.dev/docs/routes#pdfa-libreoffice.
You may set the PDF/A format and enable PDF/UA for the resulting PDF(s) with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->pdfa('PDF/A-1a')
->pdfua()
->convert(Stream::path('/path/to/my.docx'));
See https://gotenberg.dev/docs/routes#metadata-libreoffice.
You may set the metadata to write with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::libreOffice($apiUrl)
->metadata(['Producer' => 'Gotenberg'])
->convert(Stream::path('/path/to/my.docx'));
The PDF Engines module gathers all engines that can manipulate PDF files.
See https://gotenberg.dev/docs/routes#merge-pdfs-route.
Merging PDFs is as simple as:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::pdfEngines($apiUrl)
->merge(
Stream::path('/path/to/my.pdf'),
Stream::path('/path/to/my2.pdf')
);
Please note that the merging order is determined by the order of the arguments.
You may also set the PDF/A format and enable PDF/UA for the resulting PDF with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::pdfEngines($apiUrl)
->pdfa('PDF/A-1a')
->pdfua()
->merge(
Stream::path('/path/to/my.pdf'),
Stream::path('/path/to/my2.pdf'),
Stream::path('/path/to/my3.pdf')
);
You may also set the metadata to write with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::pdfEngines($apiUrl)
->metadata(['Producer' => 'Gotenberg'])
->merge(
Stream::path('/path/to/my.pdf'),
Stream::path('/path/to/my2.pdf'),
Stream::path('/path/to/my3.pdf')
);
See https://gotenberg.dev/docs/routes#convert-into-pdfa-route.
You may convert a PDF to a specific PDF/A format and enable PDF/UA with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::pdfEngines($apiUrl)
->pdfua()
->convert(
'PDF/A-1a'
Stream::path('/path/to/my.pdf')
);
If you send many PDFs, Gotenberg will return a ZIP archive with the PDFs:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::pdfEngines($apiUrl)
->outputFilename('archive')
->convert(
'PDF/A-1a',
Stream::path('/path/to/my.pdf'),
Stream::path('/path/to/my2.pdf'),
Stream::path('/path/to/my3.pdf')
);
// $filename = archive.zip
$filename = Gotenberg::save($request, $pathToSavingDirectory);
See https://gotenberg.dev/docs/routes#read-pdf-metadata-route
Gotenberg::save
method if you're using this feature.
You may retrieve one or more PDFs metadata with:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::pdfEngines($apiUrl)
->readMetadata(
Stream::path('/path/to/my.pdf'),
Stream::path('/path/to/my2.pdf')
);
This request returns a JSON formatted response with the structure filename => metadata.
See https://gotenberg.dev/docs/routes#write-pdf-metadata-route
You may write specified metadata to one or more PDFs:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::pdfEngines($apiUrl)
->writeMetadata(
[ 'Producer' => 'Gotenberg' ],
Stream::path('/path/to/my.pdf')
);
If you send many PDFs, Gotenberg will return a ZIP archive with the PDFs:
use Gotenberg\Gotenberg;
use Gotenberg\Stream;
$request = Gotenberg::pdfEngines($apiUrl)
->outputFilename('archive')
->writeMetadata(
[ 'Producer' => 'Gotenberg' ],
Stream::path('/path/to/my.pdf'),
Stream::path('/path/to/my2.pdf'),
Stream::path('/path/to/my3.pdf')
);
// $filename = archive.zip
$filename = Gotenberg::save($request, $pathToSavingDirectory);
The Webhook module is a Gotenberg middleware that sends the API responses to callbacks.
Gotenberg::save
method if you're using the webhook feature.
For instance:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->webhook('https://my.webhook.url', 'https://my.webhook.error.url')
->pdf()
->url('https://my.url');
You may also override the default HTTP method (POST
) that Gotenberg will use to call the webhooks:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->webhook('https://my.webhook.url', 'https://my.webhook.error.url')
->webhookMethod('PATCH')
->webhookErrorMethod('PUT')
->pdf()
->url('https://my.url');
You may also tell Gotenberg to add extra HTTP headers that it will send alongside the request to the webhooks:
use Gotenberg\Gotenberg;
$request = Gotenberg::chromium($apiUrl)
->webhook('https://my.webhook.url', 'https://my.webhook.error.url')
->webhookExtraHttpHeaders([
'My-Header-1' => 'My value',
'My-Header-2' => 'My value'
])
->pdf()
->url('https://my.url');