updating for Gotenberg v3

Author: Julien Neuhart

README.md

@@ -1,27 +1,6 @@
-<h3 align="center">Gotenberg PHP Client</h3>
-<p align="center">A PHP client for the Gotenberg API</p>
-<p align="center">
-    <a href="https://travis-ci.org/thecodingmachine/gotenberg-php-client">
-        <img src="https://travis-ci.org/thecodingmachine/gotenberg-php-client.svg?branch=master" alt="Travis CI">
-    </a>
-    <a href="https://scrutinizer-ci.com/g/thecodingmachine/gotenberg-php-client/?branch=master">
-        <img src="https://scrutinizer-ci.com/g/thecodingmachine/gotenberg-php-client/badges/quality-score.png?b=master" alt="Scrutinizer">
-    </a>
-    <a href="https://codecov.io/gh/thecodingmachine/gotenberg-php-client/branch/master">
-        <img src="https://codecov.io/gh/thecodingmachine/gotenberg-php-client/branch/master/graph/badge.svg" alt="Codecov">
-    </a>
-</p>
+# Gotenberg PHP client
 
----
-
-[Gotenberg](https://github.com/thecodingmachine/gotenberg) is a stateless API for converting Markdown files, HTML files and Office documents to PDF.
-This package helps you to interact with this API using PHP.
-
-# Menu
-
-* [Install](#install)
-* [Docker](#docker)
-* [Usage](#usage)
+A simple PHP client for interacting with a Gotenberg API.
 
 ## Install
 
@@ -37,31 +16,6 @@ Then the PHP client:
 $ composer require thecodingmachine/gotenberg-php-client
 ```
 
-## Docker
-
-As the [Gotenberg](https://github.com/thecodingmachine/gotenberg) API is provided within a Docker image, you'll have to add it
-to your Docker Compose stack:
-
-```yaml
-version: '3'
-
-services:
-
-  # your others services
-
-  gotenberg:
-    image: thecodingmachine/gotenberg:2.0.0
-```
-
-You may now start your stack using:
-
-```bash
-$ docker-compose up --scale gotenberg=your_number_of_instances
-```
-
-When requesting the Gotenberg service with your client, Docker will automatically redirect a request to a Gotenberg container
-according to the round-robin strategy.
-
 ## Usage
 
 ```php
@@ -72,8 +26,9 @@ namespace YourAwesomeNamespace;
 use TheCodingMachine\Gotenberg\Client;
 use TheCodingMachine\Gotenberg\ClientException;
 use TheCodingMachine\Gotenberg\DocumentFactory;
-
-use GuzzleHttp\Psr7\LazyOpenStream;
+use TheCodingMachine\Gotenberg\HTMLRequest;
+use TheCodingMachine\Gotenberg\Request;
+use TheCodingMachine\Gotenberg\RequestException;
 
 class YourAwesomeClass {
 
@@ -83,39 +38,47 @@ class YourAwesomeClass {
         # or the following if you want the client to discover automatically an installed implementation of the PSR7 `HttpClient`.
         $client = new Client('gotenberg:3000');
 
-        # let's instantiate some documents you wish to convert.
-        $yourOfficeDocument = DocumentFactory::makeFromPath('file.docx', '/path/to/file');
-        $yourHTMLDocument = DocumentFactory::makeFromStream('file.html', new LazyOpenStream('path/to/file', 'r'));
+        # HTML conversion example.
+        $index = DocumentFactory::makeFromPath('index.html', '/path/to/file');
+        $header = DocumentFactory::makeFromPath('header.html', '/path/to/file');
+        $footer = DocumentFactory::makeFromPath('footer.html', '/path/to/file');
+        $assets = [
+            DocumentFactory::makeFromPath('style.css', '/path/to/file'),
+            DocumentFactory::makeFromPath('img.png', '/path/to/file'),
+        ];
 
-        # now let's send those documents!
         try {
+            $request = new HTMLRequest($index);
+            $request->setHeader($header);
+            $request->setFooter($footer);
+            $request->setAssets($assets);
+            $request->setPaperSize(Request::A4);
+            $request->setMargins(Request::NO_MARGINS);
+            
             # store method allows you to... store the resulting PDF in a particular folder.
             # this method also returns the resulting PDF path.
-            $filePath = $client->store([
-                $yourOfficeDocument,
-                $yourHTMLDocument
-            ], 'path/to/folder/you/want/the/pdf/to/be/store');
+            $filePath = $client->store($request, 'path/to/folder/you/want/the/pdf/to/be/store');
 
             # if you wish to redirect the response directly to the browser, you may also use:
-            $response = $client->forward([
-                $yourOfficeDocument,
-                $yourHTMLDocument
-            ]);
+            $response = $client->post($request);
 
+        } catch (RequestException $e) {
+            # this exception is thrown is given paper size or margins are not correct.
         } catch (ClientException $e) {
             # this exception is thrown by the client if the API has returned a code != 200.
         } catch (\Http\Client\Exception $e) {
             # some PSR7 exception.
         } catch (\Exception $e) {
             # some (random?) exception.
         }
-    }
-    
+    }  
 }
 ```
 
-Voilà! :smiley:
+For more complete usages, head to the [documentation](https://thecodingmachine.github.io/gotenberg).
 
----
+## Badges
 
-Would you like to update this documentation ? Feel free to open an [issue](../../issues).
+[![Travis CI](https://travis-ci.org/thecodingmachine/gotenberg-php-client.svg?branch=master)](https://travis-ci.org/thecodingmachine/gotenberg-php-client)
+[![Scrutinizer](https://scrutinizer-ci.com/g/thecodingmachine/gotenberg-php-client/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/thecodingmachine/gotenberg-php-client/?branch=master)
+[![Codecov](https://codecov.io/gh/thecodingmachine/gotenberg-php-client/branch/master/graph/badge.svg)](https://codecov.io/gh/thecodingmachine/gotenberg-php-client/branch/master)

composer.json

@@ -28,13 +28,15 @@
     "php-http/httplug": "^1.0",
     "php-http/discovery": "^1.0",
     "guzzlehttp/psr7": "^1.4.2",
-    "php-http/message": "^1.0"
+    "php-http/message": "^1.0",
+    "thecodingmachine/safe": "^0.1.8"
   },
   "require-dev" : {
     "phpunit/phpunit": "^7",
     "squizlabs/php_codesniffer": "^3.2",
-    "phpstan/phpstan": "^0.9.2",
-    "thecodingmachine/phpstan-strict-rules": "^0.9.0",
+    "phpstan/phpstan": "^0.10.5",
+    "thecodingmachine/phpstan-safe-rule": "^0.1.0",
+    "thecodingmachine/phpstan-strict-rules": "^0.10.7",
     "php-http/mock-client": "^1.0",
     "php-http/guzzle6-adapter": "^1.1"
   },
@@ -56,7 +58,7 @@
   },
   "extra": {
     "branch-alias": {
-      "dev-master": "2.0.x-dev"
+      "dev-master": "3.0.x-dev"
     }
   }
 }

docker-compose.yml

@@ -3,7 +3,7 @@ version: '3'
 services:
 
   php:
-    image: thecodingmachine/php:7.1-v1-cli
+    image: thecodingmachine/php:7.2-v2-cli
     container_name: php
     environment:
       - PHP_EXTENSION_XDEBUG=1
@@ -12,6 +12,6 @@ services:
       - ./:/usr/src/app:rw
 
   gotenberg:
-    image: thecodingmachine/gotenberg:2.0.0
+    image: thecodingmachine/gotenberg:3
     container_name: gotenberg
     restart: 'no'

phpstan.neon

@@ -1,5 +1,3 @@
-#parameters:
-#    ignoreErrors:
-#     - "#Instantiated class WeakRef not found.#"
 includes:
-    - vendor/thecodingmachine/phpstan-strict-rules/phpstan-strict-rules.neon
+    - vendor/thecodingmachine/phpstan-strict-rules/phpstan-strict-rules.neon
+    - vendor/thecodingmachine/phpstan-safe-rule/phpstan-safe-rule.neon

phpunit.xml.dist

@@ -7,8 +7,7 @@
          convertNoticesToExceptions="true"
          convertWarningsToExceptions="true"
          processIsolation="false"
-         stopOnFailure="false"
-         syntaxCheck="false">
+         stopOnFailure="false">
 
     <testsuites>
         <testsuite name="Test Suite">

src/Client.php

@@ -8,8 +8,13 @@
 use Http\Discovery\MessageFactoryDiscovery;
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
+use Safe\Exceptions\FilesystemException;
+use function Safe\mkdir;
+use function Safe\fopen;
+use function Safe\fwrite;
+use function Safe\fclose;
 
-class Client
+final class Client
 {
     /** @var HttpClient */
     private $client;
@@ -31,67 +36,70 @@ public function __construct(string $apiURL, HttpClient $client = null)
     /**
      * Sends the given documents to the API and returns the response.
      *
-     * @param Document[] $documents
+     * @param GotenbergRequestInterface $request
      * @return ResponseInterface
      * @throws ClientException
      * @throws \Exception
-     * @throws \Http\Client\Exception
+     * @throws FilesystemException
      */
-    public function forward(array $documents): ResponseInterface
+    public function post(GotenbergRequestInterface $request): ResponseInterface
     {
-        return $this->handleResponse($this->client->sendRequest($this->makeMultipartFormDataRequest($documents)));
+        return $this->handleResponse($this->client->sendRequest($this->makeMultipartFormDataRequest($request)));
     }
 
     /**
      * Sends the given documents to the API, stores the resulting PDF in the given storing path
      * and returns the resulting PDF path.
      *
-     * @param Document[] $documents
+     * @param GotenbergRequestInterface $request
      * @param string $storingPath
      * @return string
      * @throws ClientException
      * @throws \Exception
-     * @throws \Http\Client\Exception
+     * @throws FilesystemException
      */
-    public function store(array $documents, string $storingPath): string
+    public function store(GotenbergRequestInterface $request, string $storingPath): string
     {
-        $response = $this->handleResponse($this->client->sendRequest($this->makeMultipartFormDataRequest($documents)));
-
+        $response = $this->handleResponse($this->client->sendRequest($this->makeMultipartFormDataRequest($request)));
         if (!is_dir($storingPath)) {
             mkdir($storingPath);
         }
-
         $filePath = $storingPath . '/' . uniqid() . '.pdf';
         $fileStream = $response->getBody();
-
         $fp = fopen($filePath, 'w');
         fwrite($fp, $fileStream);
         fclose($fp);
-
         return $filePath;
     }
 
     /**
-     * @param Document[] $documents
+     * @param GotenbergRequestInterface $request
      * @return RequestInterface
      */
-    private function makeMultipartFormDataRequest(array $documents): RequestInterface
+    private function makeMultipartFormDataRequest(GotenbergRequestInterface $request): RequestInterface
     {
         $multipartData = [];
-
-        foreach ($documents as $document) {
+        foreach ($request->getFormValues() as $fieldName => $fieldValue) {
+            $multipartData[] = [
+                'name' => $fieldName,
+                'contents' => $fieldValue,
+            ];
+        }
+        /**
+         * @var string $filename
+         * @var Document $document
+         */
+        foreach ($request->getFormFiles() as $filename => $document) {
             $multipartData[] = [
                 'name' => 'files',
-                'filename' => $document->getFileName(),
+                'filename' => $filename,
                 'contents' => $document->getFileStream()
             ];
         }
-
         $body = new MultipartStream($multipartData);
         $messageFactory = MessageFactoryDiscovery::find();
-
         return $messageFactory
-            ->createRequest('POST', $this->apiURL)
+            ->createRequest('POST', $this->apiURL . $request->getPostURL())
             ->withHeader('Content-Type', 'multipart/form-data; boundary="' . $body->getBoundary() . '"')
             ->withBody($body);
     }

src/ClientException.php

@@ -2,7 +2,7 @@
 
 namespace TheCodingMachine\Gotenberg;
 
-class ClientException extends \Exception
+final class ClientException extends \Exception
 {
 
 }

src/Document.php

@@ -4,7 +4,7 @@
 
 use Psr\Http\Message\StreamInterface;
 
-class Document
+final class Document
 {
     /** @var string */
     private $fileName;

src/DocumentFactory.php

@@ -5,7 +5,7 @@
 use GuzzleHttp\Psr7\LazyOpenStream;
 use Psr\Http\Message\StreamInterface;
 
-class DocumentFactory
+final class DocumentFactory
 {
     /**
      * @param string $fileName

src/GotenbergRequestInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace TheCodingMachine\Gotenberg;
+
+interface GotenbergRequestInterface
+{
+    /**
+     * @return string
+     */
+    public function getPostURL(): string;
+
+    /**
+     * @return array<string,mixed>
+     */
+    public function getFormValues(): array;
+
+    /**
+     * @return array<string,Document>
+     */
+    public function getFormFiles(): array;
+}