Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gotenberg/gotenberg-php

🐘 A PHP client for interacting with Gotenberg.
https://github.com/gotenberg/gotenberg-php

chromium conversion csv docx excel google-chrome gotenberg html libreoffice markdown pdf pdftk php pptx puppeteer unoconv wkhtmltopdf word xlsx

Last synced: about 5 hours ago
JSON representation

🐘 A PHP client for interacting with Gotenberg.

Awesome Lists containing this project

README 

        


    Gotenberg PHP Logo

    
Gotenberg PHP


    
A PHP client for interacting with Gotenberg


    


        Latest Version

        Total Downloads

        Continuous Integration

        https://codecov.io/gh/gotenberg/gotenberg

    



---



This package is a PHP client for [Gotenberg](https://gotenberg.dev), 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](https://github.com/thecodingmachine/gotenberg-php-client) |



## Quick Examples



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



```php

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:



```php

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](https://gotenberg.dev), a Docker-powered stateless API for PDF files.



See the [installation guide](https://gotenberg.dev/docs/getting-started/installation) 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:



```php

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:



```php

use Gotenberg\Gotenberg;



Gotenberg::chromium($apiUrl)

    ->pdf()                  // Or screenshot().

    ->singlePage()           // Optional.

    ->url('https://my.url'));

```



> [!TIP]

> Head to the [documentation](https://gotenberg.dev/) to learn about all possibilities.



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



```php

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', '
Hello, world!
'));



// 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:



1. Get the response from the API and handle it according to your need.

2. 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:



```php

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](#installation)), you may also use `Gotenberg::send`:



```php

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:



```php

use Gotenberg\Gotenberg;



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

```



### Save the resulting file



If you have a *PSR-18* compatible HTTP client (see [Installation](#installation)), you may use `Gotenberg::save`:



```php

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:



```php

use Gotenberg\Gotenberg;



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

```



### Filename



You may override the output filename with:



```php

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:



```php

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:



```php

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:



```php

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

}

```