gotenberg / gotenberg-php
A PHP client for interacting with Gotenberg, a developer-friendly API for converting numerous document formats into PDF files, and more!
Fund package maintenance!
gulien
Installs: 1 964 339
Dependents: 8
Suggesters: 2
Security: 0
Stars: 237
Watchers: 6
Forks: 16
Open Issues: 0
Requires
- php: ^8.1|^8.2|^8.3|^8.4
- ext-json: *
- ext-mbstring: *
- guzzlehttp/psr7: ^1 || ^2.1
- php-http/discovery: ^1.14
- psr/http-client: ^1.0
- psr/http-message: ^1.0|^2.0
Requires (Dev)
- doctrine/coding-standard: ^12.0
- pestphp/pest: ^2.28
- phpstan/phpstan: ^1.12
- squizlabs/php_codesniffer: ^3.10
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!
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 Docker-powered stateless API for PDF files.
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:
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.
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.
Trace or request ID
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('$apiUrl') ->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($apiUrl) ->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($apiUrl) ->screenshot() ->url('https://my.url') ); } catch (GotenbergApiErrored $e) { $trace = $e->getGotenbergTrace(); // Or if you override the header name: $trace = $e->getGotenbergTrace('Request-Id'); }