chore: improve README

gotenberg · Sep 23, 2024 · 7a2c187 · 7a2c187
1 parent fd22cd4
commit 7a2c187
Showing 1 changed file with 65 additions and 23 deletions.
diff --git 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,26 +79,73 @@ 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('<html><body><p>Hello, world!</p></body></html>'));
+
+// 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:
 
 ```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 🚀