From 7a2c187724d5cd0eefaca9e79877abc4cc79bc6b Mon Sep 17 00:00:00 2001 From: Julien Neuhart Date: Mon, 23 Sep 2024 13:50:38 +0200 Subject: [PATCH] chore: improve README --- README.md | 88 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 65 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index e169e14..bf29c0c 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,11 @@ This package is a PHP client for [Gotenberg](https://gotenberg.dev), a developer 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](https://github.com/thecodingmachine/gotenberg-php-client) instead. - -For **Gotenberg 7.x**, use version `v1.1.8`. +| Gotenberg version | Client | +|-------------------|---------------------------------------------------------------------------------------------------| +| `8.x` | `v2.x` **(current)** | +| `7.x` | `v1.x` | +| `6.x` | [thecodingmachine/gotenberg-php-client](https://github.com/thecodingmachine/gotenberg-php-client) | ## Quick Examples @@ -36,16 +36,15 @@ $filename = Gotenberg::save( ); ``` -You may also convert Office documents and merge them: +You may also convert Office documents: ```php use Gotenberg\Gotenberg; use Gotenberg\Stream; -// Converts Office documents to PDF and merges them. +// Converts Office documents to PDF. $response = Gotenberg::send( Gotenberg::libreOffice($apiUrl) - ->merge() ->convert( Stream::path($pathToDocx), Stream::path($pathToXlsx) @@ -80,15 +79,62 @@ If you're not sure which adapter you should use, consider using the `php-http/gu 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. + ->skipNetworkIdleEvent() // 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\Gotenberg; +use Gotenberg\Stream; + +Gotenberg::libreOffice($apiUrl) + ->convert(Stream::path($pathToDocument)); + +// Alternatively, you may also set the content directly. +Gotenberg::chromium($apiUrl) + ->pdf() + ->html(Stream::string('

Hello, world!

')); + +// Or create your stream from scratch. +Gotenberg::libreOffice($apiUrl) + ->convert(new Stream('document.docx', $stream)); +``` + ## Send a request to the API -After having created the HTTP request (see below), you have two options: +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. -> In the following examples, we assume the Gotenberg API is available at http://localhost:3000. - ### Get a response You may use any HTTP client that is able to handle a *PSR-7* `RequestInterface` to call the API: @@ -96,10 +142,10 @@ You may use any HTTP client that is able to handle a *PSR-7* `RequestInterface` ```php use Gotenberg\Gotenberg; -$request = Gotenberg::chromium('http://localhost:3000') +$request = Gotenberg::chromium($apiUrl) ->pdf() ->url('https://my.url'); - + $response = $client->sendRequest($request); ``` @@ -108,7 +154,7 @@ If you have a *PSR-18* compatible HTTP client (see [Installation](#installation) ```php use Gotenberg\Gotenberg; -$request = Gotenberg::chromium('http://localhost:3000') +$request = Gotenberg::chromium($apiUrl) ->pdf() ->url('https://my.url'); @@ -138,7 +184,7 @@ If you have a *PSR-18* compatible HTTP client (see [Installation](#installation) ```php use Gotenberg\Gotenberg; -$request = Gotenberg::chromium('http://localhost:3000') +$request = Gotenberg::chromium($apiUrl) ->pdf() ->url('https://my.url'); @@ -163,7 +209,7 @@ You may override the output filename with: ```php use Gotenberg\Gotenberg; -$request = Gotenberg::chromium('http://localhost:3000') +$request = Gotenberg::chromium($apiUrl) ->pdf() ->outputFilename('my_file') ->url('https://my.url'); @@ -178,7 +224,7 @@ By default, Gotenberg creates a *UUID* trace that identifies a request in its lo ```php use Gotenberg\Gotenberg; -$request = Gotenberg::chromium('http://localhost:3000') +$request = Gotenberg::chromium('$apiUrl') ->pdf() ->trace('debug') ->url('https://my.url'); @@ -189,7 +235,7 @@ It will set the header `Gotenberg-Trace` with your value. You may also override ```php use Gotenberg\Gotenberg; -$request = Gotenberg::chromium('http://localhost:3000') +$request = Gotenberg::chromium($apiUrl) ->pdf() ->trace('debug', 'Request-Id') ->url('https://my.url'); @@ -207,7 +253,7 @@ use Gotenberg\Gotenberg; try { $response = Gotenberg::send( - Gotenberg::chromium('http://localhost:3000') + Gotenberg::chromium($apiUrl) ->screenshot() ->url('https://my.url') ); @@ -217,7 +263,3 @@ try { $trace = $e->getGotenbergTrace('Request-Id'); } ``` - -## More - -Head to the [documentation](https://gotenberg.dev/) to learn how to interact with Gotenberg 🚀