From 25f7ba3ee6c82d70164f98a98650fc99fc0b571a Mon Sep 17 00:00:00 2001 From: Julien Neuhart Date: Mon, 28 Jan 2019 15:18:12 +0100 Subject: [PATCH] 4.0.0 (#42) * adding URL conversions * updating gotenberg version in documentation * pkg: input as variadic string (#39) * pkg: input as variadic string * pkg: fix link to github doc * update doc about v4 client * make doc * fixing missing variadic inputs in doc * adding more fonts * updating PHP documentation --- README.md | 4 +- build/base/Dockerfile | 39 ++++- build/base/fonts.conf | 29 ++++ build/docs/content/01-install.md | 4 +- build/docs/content/02-html.md | 16 +- build/docs/content/03-url.md | 56 +++++++ .../{03-markdown.md => 04-markdown.md} | 6 +- .../content/{04-office.md => 05-office.md} | 24 +-- .../docs/content/{05-merge.md => 06-merge.md} | 6 +- .../content/{06-webhook.md => 07-webhook.md} | 0 .../{07-scalability.md => 08-scalability.md} | 2 +- .../{08-liveness.md => 09-liveness.md} | 0 build/docs/content/10-fonts.md | 13 ++ .../docs/content/{09-links.md => 11-links.md} | 0 docs/index.html | 148 +++++++++++++----- go.mod | 2 +- go.sum | 2 + internal/app/api/api.go | 1 + internal/app/api/resource.go | 10 ++ internal/app/api/url.go | 51 ++++++ internal/app/api/url_test.go | 24 +++ pkg/README.md | 4 +- pkg/client.go | 2 +- pkg/doc.go | 2 +- pkg/html.go | 2 +- pkg/html_test.go | 4 +- pkg/markdown.go | 4 +- pkg/markdown_test.go | 12 +- pkg/merge.go | 2 +- pkg/merge_test.go | 4 +- pkg/office.go | 2 +- pkg/office_test.go | 4 +- pkg/url.go | 85 ++++++++++ pkg/url_test.go | 41 +++++ test/testdata/url/footer.html | 15 ++ test/testdata/url/header.html | 13 ++ test/testfunc.go | 23 +++ 37 files changed, 553 insertions(+), 103 deletions(-) create mode 100644 build/base/fonts.conf create mode 100644 build/docs/content/03-url.md rename build/docs/content/{03-markdown.md => 04-markdown.md} (90%) rename build/docs/content/{04-office.md => 05-office.md} (82%) rename build/docs/content/{05-merge.md => 06-merge.md} (88%) rename build/docs/content/{06-webhook.md => 07-webhook.md} (100%) rename build/docs/content/{07-scalability.md => 08-scalability.md} (92%) rename build/docs/content/{08-liveness.md => 09-liveness.md} (100%) create mode 100644 build/docs/content/10-fonts.md rename build/docs/content/{09-links.md => 11-links.md} (100%) create mode 100644 internal/app/api/url.go create mode 100644 internal/app/api/url_test.go create mode 100644 pkg/url.go create mode 100644 pkg/url_test.go create mode 100644 test/testdata/url/footer.html create mode 100644 test/testdata/url/header.html diff --git a/README.md b/README.md index 5927a098..98362773 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ At TheCodingMachine, we build a lot of web applications (intranets, extranets an Open a terminal and run the following command: ```bash -$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:3 +$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:4 ``` The API is now available on your host at `http://localhost:3000`. @@ -33,7 +33,7 @@ to learn how to interact with it! ## Badges -[![Docker image layers](https://images.microbadger.com/badges/image/thecodingmachine/gotenberg:3.svg)](https://microbadger.com/images/thecodingmachine/gotenberg:3) +[![Docker image layers](https://images.microbadger.com/badges/image/thecodingmachine/gotenberg:4.svg)](https://microbadger.com/images/thecodingmachine/gotenberg:4) [![Travis CI](https://travis-ci.org/thecodingmachine/gotenberg.svg?branch=master)](https://travis-ci.org/thecodingmachine/gotenberg) [![GoDoc](https://godoc.org/github.com/thecodingmachine/gotenberg?status.svg)](https://godoc.org/github.com/thecodingmachine/gotenberg) [![Go Report Card](https://goreportcard.com/badge/github.com/thecodingmachine/gotenberg)](https://goreportcard.com/report/thecodingmachine/gotenberg) diff --git a/build/base/Dockerfile b/build/base/Dockerfile index 4d11b724..202b1b3b 100644 --- a/build/base/Dockerfile +++ b/build/base/Dockerfile @@ -10,7 +10,7 @@ FROM debian:9.5-slim RUN echo "deb http://httpredir.debian.org/debian/ stretch main contrib non-free" > /etc/apt/sources.list &&\ apt-get update &&\ - apt-get install -y curl wget python3-pip + apt-get install -y curl wget python3-pip ttf-mscorefonts-installer # |-------------------------------------------------------------------------- # | PM2 @@ -66,4 +66,39 @@ RUN pip3 install unoconv &&\ # | https://github.com/thecodingmachine/gotenberg/issues/29 # | -RUN apt-get -y install pdftk \ No newline at end of file +RUN apt-get -y install pdftk + +# |-------------------------------------------------------------------------- +# | Fonts +# |-------------------------------------------------------------------------- +# | +# | Installs a handful of fonts. +# | Note: ttf-mscorefonts-installer are installed on top of this Dockerfile. +# | + +# Credits: +# https://github.com/arachnys/athenapdf/blob/master/cli/Dockerfile +# https://help.accusoft.com/PrizmDoc/v12.1/HTML/Installing_Asian_Fonts_on_Ubuntu_and_Debian.html +RUN apt-get install -y \ + culmus \ + fonts-beng \ + fonts-hosny-amiri \ + fonts-lklug-sinhala \ + fonts-lohit-guru \ + fonts-lohit-knda \ + fonts-samyak-gujr \ + fonts-samyak-mlym \ + fonts-samyak-taml \ + fonts-sarai \ + fonts-sil-abyssinica \ + fonts-sil-padauk \ + fonts-telu \ + fonts-thai-tlwg \ + ttf-liberation \ + ttf-wqy-zenhei \ + fonts-arphic-uming \ + fonts-ipafont-mincho \ + fonts-ipafont-gothic \ + fonts-unfonts-core + +COPY build/base/fonts.conf /etc/fonts/conf.d/100-gotenberg.conf diff --git a/build/base/fonts.conf b/build/base/fonts.conf new file mode 100644 index 00000000..344ccbef --- /dev/null +++ b/build/base/fonts.conf @@ -0,0 +1,29 @@ + + + + + + rgb + + + + + true + + + + + hintslight + + + + + true + + + + + lcddefault + + + \ No newline at end of file diff --git a/build/docs/content/01-install.md b/build/docs/content/01-install.md index 69d23403..c9825a89 100644 --- a/build/docs/content/01-install.md +++ b/build/docs/content/01-install.md @@ -7,7 +7,7 @@ Gotenberg is shipped within a Docker image. You may start it with: ```bash -$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:3 +$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:4 ``` > The API will be available at [http://localhost:3000](http://localhost:3000). @@ -22,7 +22,7 @@ services: # your others services gotenberg: - image: thecodingmachine/gotenberg:3 + image: thecodingmachine/gotenberg:4 ``` > The API will be available under `gotenberg:3000` in your Docker Compose network. diff --git a/build/docs/content/02-html.md b/build/docs/content/02-html.md index f56c0a55..ba270429 100644 --- a/build/docs/content/02-html.md +++ b/build/docs/content/02-html.md @@ -185,7 +185,7 @@ But this won't: You may also use *remote* paths for Google fonts, images and so on. > If you want to install fonts directly in the Gotenberg Docker image, -> see to the [fonts section](#office.fonts). +> see to the [fonts section](#fonts). ### cURL @@ -208,11 +208,7 @@ import "github.com/thecodingmachine/gotenberg/pkg" func main() { c := &gotenberg.Client{Hostname: "http://localhost:3000"} req, _ := gotenberg.NewHTMLRequest("index.html") - req.SetAssets([]string{ - "font.woff", - "img.gif", - "style.css", - }) + req.SetAssets("font.woff", "img.gif", "style.css") dest := "result.pdf" c.Store(req, dest) } @@ -234,8 +230,8 @@ $assets = [ ]; $request = new HTMLRequest($index); $request->setAssets($assets); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); +$dest = "result.pdf"; +$client->store($request, $dest); ``` ## Paper size, margins, orientation @@ -294,6 +290,6 @@ $request = new HTMLRequest($index); $request->setPaperSize(Request::A4); $request->setMargins(Request::NO_MARGINS); $request->setLandscape(true); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); +$dest = "result.pdf"; +$client->store($request, $dest); ``` \ No newline at end of file diff --git a/build/docs/content/03-url.md b/build/docs/content/03-url.md new file mode 100644 index 00000000..2dc99682 --- /dev/null +++ b/build/docs/content/03-url.md @@ -0,0 +1,56 @@ +--- +title: URL +--- + +Gotenberg provides the endpoint `/convert/url` for remote URL conversions. + +It accepts `POST` requests with a `multipart/form-data` Content-Type. + +## Basic + +This endpoint does not accept an `index.html` file nor assets files but a form field +named `remoteURL` instead. Otherwise, URL conversions work the same as HTML conversions. + +> **Attention:** when converting a website to PDF, you should remove all margins. +> If not, some of the content of the page might be hidden. + +### cURL + +```bash +$ curl --request POST \ + --url http://localhost:3000/convert/url \ + --header 'Content-Type: multipart/form-data' \ + --form remoteURL=https://google.com + --form marginTop=0 \ + --form marginBottom=0 \ + --form marginLeft=0 \ + --form marginRight=0 \ + -o result.pdf +``` + +### Go + +```golang +import "github.com/thecodingmachine/gotenberg/pkg" + +func main() { + c := &gotenberg.Client{Hostname: "http://localhost:3000"} + req := gotenberg.NewURLRequest("https://google.com") + req.SetMargins(gotenberg.NoMargins) + dest := "result.pdf" + c.Store(req, dest) +} +``` + +### PHP + +```php +use TheCodingMachine\Gotenberg\Client; +use TheCodingMachine\Gotenberg\URLRequest; + +$client = new Client('http://localhost:3000', new \Http\Adapter\Guzzle6\Client()); +$request = new URLRequest('https://google.com'); +$request->setMargins(Request::NO_MARGINS); +$dest = "result.pdf"; +$filename = $client->store($request, $dest); +``` diff --git a/build/docs/content/03-markdown.md b/build/docs/content/04-markdown.md similarity index 90% rename from build/docs/content/03-markdown.md rename to build/docs/content/04-markdown.md index 278f29df..65f4e13b 100644 --- a/build/docs/content/03-markdown.md +++ b/build/docs/content/04-markdown.md @@ -46,7 +46,7 @@ import "github.com/thecodingmachine/gotenberg/pkg" func main() { c := &gotenberg.Client{Hostname: "http://localhost:3000"} - req, _ := gotenberg.NewMarkdownRequest("index.html", []string{"file.md"}) + req, _ := gotenberg.NewMarkdownRequest("index.html", "file.md") dest := "result.pdf" c.Store(req, dest) } @@ -65,6 +65,6 @@ $markdowns = [ DocumentFactory::makeFromPath('file.md', 'file.md'), ]; $request = new MarkdownRequest($index, $markdowns); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); +$dest = "result.pdf"; +$filename = $client->store($request, $dest); ``` diff --git a/build/docs/content/04-office.md b/build/docs/content/05-office.md similarity index 82% rename from build/docs/content/04-office.md rename to build/docs/content/05-office.md index ae50a364..dfcc5535 100644 --- a/build/docs/content/04-office.md +++ b/build/docs/content/05-office.md @@ -46,7 +46,7 @@ import "github.com/thecodingmachine/gotenberg/pkg" func main() { c := &gotenberg.Client{Hostname: "http://localhost:3000"} - req, _ := gotenberg.NewOfficeRequest([]string{"document.docx", "document2.docx"}) + req, _ := gotenberg.NewOfficeRequest("document.docx", "document2.docx") dest := "result.pdf" c.Store(req, dest) } @@ -65,8 +65,8 @@ $files = [ DocumentFactory::makeFromPath('document2.docx', 'document2.docx'), ]; $request = new OfficeRequest($files); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); +$dest = "result.pdf"; +$filename = $client->store($request, $dest); ``` ## Orientation @@ -93,7 +93,7 @@ import "github.com/thecodingmachine/gotenberg/pkg" func main() { c := &gotenberg.Client{Hostname: "http://localhost:3000"} - req, _ := gotenberg.NewOfficeRequest([]string{"document.docx"}) + req, _ := gotenberg.NewOfficeRequest("document.docx") req.SetLandscape(true) dest := "result.pdf" c.Store(req, dest) @@ -113,18 +113,6 @@ $files = [ ]; $request = new OfficeRequest($files); $request->setLandscape(true); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); -``` - -## Fonts - -By default, only `ttf-mscorefonts` fonts are installed. - -If you wish to use more fonts, you will have to create your own image: - -```Dockerfile -FROM thecodingmachine/gotenberg:3 - -RUN apt-get -y install yourfonts +$dest = "result.pdf"; +$filename = $client->store($request, $dest); ``` diff --git a/build/docs/content/05-merge.md b/build/docs/content/06-merge.md similarity index 88% rename from build/docs/content/05-merge.md rename to build/docs/content/06-merge.md index f825854a..f51d5601 100644 --- a/build/docs/content/05-merge.md +++ b/build/docs/content/06-merge.md @@ -29,7 +29,7 @@ import "github.com/thecodingmachine/gotenberg/pkg" func main() { c := &gotenberg.Client{Hostname: "http://localhost:3000"} - req, _ := gotenberg.NewMergeRequest([]string{"file.pdf", "file2.pdf"}) + req, _ := gotenberg.NewMergeRequest("file.pdf", "file2.pdf") dest := "result.pdf" c.Store(req, dest) } @@ -48,6 +48,6 @@ $files = [ DocumentFactory::makeFromPath('file2.pdf', 'file2.pdf'), ]; $request = new MergeRequest($files); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); +$dest = "result.pdf"; +$filename = $client->store($request, $dest); ``` \ No newline at end of file diff --git a/build/docs/content/06-webhook.md b/build/docs/content/07-webhook.md similarity index 100% rename from build/docs/content/06-webhook.md rename to build/docs/content/07-webhook.md diff --git a/build/docs/content/07-scalability.md b/build/docs/content/08-scalability.md similarity index 92% rename from build/docs/content/07-scalability.md rename to build/docs/content/08-scalability.md index 0d72a119..906cc6dd 100644 --- a/build/docs/content/07-scalability.md +++ b/build/docs/content/08-scalability.md @@ -14,7 +14,7 @@ services: # your others services gotenberg: - image: thecodingmachine/gotenberg:3 + image: thecodingmachine/gotenberg:4 ``` You may now launch your services using: diff --git a/build/docs/content/08-liveness.md b/build/docs/content/09-liveness.md similarity index 100% rename from build/docs/content/08-liveness.md rename to build/docs/content/09-liveness.md diff --git a/build/docs/content/10-fonts.md b/build/docs/content/10-fonts.md new file mode 100644 index 00000000..daa7e040 --- /dev/null +++ b/build/docs/content/10-fonts.md @@ -0,0 +1,13 @@ +--- +title: Fonts +--- + +By default, a handful of fonts are installed. Asian characters are also supported out of the box. + +If you wish to use more fonts, you will have to create your own image: + +```Dockerfile +FROM thecodingmachine/gotenberg:4 + +RUN apt-get -y install yourfonts +``` \ No newline at end of file diff --git a/build/docs/content/09-links.md b/build/docs/content/11-links.md similarity index 100% rename from build/docs/content/09-links.md rename to build/docs/content/11-links.md diff --git a/docs/index.html b/docs/index.html index f8b71326..41a39bf1 100755 --- a/docs/index.html +++ b/docs/index.html @@ -45,6 +45,10 @@ HTML +
+ URL +
+
Markdown
@@ -69,6 +73,10 @@ Liveness +
+ Fonts +
+
Links
@@ -103,7 +111,7 @@

You may start it with:

-
$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:3
+
$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:4
 

 
 

@@ -119,7 +127,7 @@
   # your others services
 
   gotenberg:
-    image: thecodingmachine/gotenberg:3
+    image: thecodingmachine/gotenberg:4
@@ -354,7 +362,7 @@ are on the same level as the index.html file.

If you want to install fonts directly in the Gotenberg Docker image, -see to the fonts section.

+see to the fonts section.

fonts section.

func main() { c := &gotenberg.Client{Hostname: "http://localhost:3000"} req, _ := gotenberg.NewHTMLRequest("index.html") - req.SetAssets([]string{ - "font.woff", - "img.gif", - "style.css", - }) + req.SetAssets("font.woff", "img.gif", "style.css") dest := "result.pdf" c.Store(req, dest) } @@ -407,8 +411,8 @@ $assets = [ ]; $request = new HTMLRequest($index); $request->setAssets($assets); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); +$dest = "result.pdf"; +$client->store($request, $dest);

URL

+

Gotenberg provides the endpoint /convert/url for remote URL conversions.

+ +

It accepts POST requests with a multipart/form-data Content-Type.

+ +

Basic

+ +

This endpoint does not accept an index.html file nor assets files but a form field +named remoteURL instead. Otherwise, URL conversions work the same as HTML conversions.

+ +
+

Attention: when converting a website to PDF, you should remove all margins. +If not, some of the content of the page might be hidden.

+
+ +

cURL

+ +
$ curl --request POST \
+    --url http://localhost:3000/convert/url \
+    --header 'Content-Type: multipart/form-data' \
+    --form remoteURL=https://google.com
+    --form marginTop=0 \
+    --form marginBottom=0 \
+    --form marginLeft=0 \
+    --form marginRight=0 \
+    -o result.pdf
+
+ +

Go

+ +
import "github.com/thecodingmachine/gotenberg/pkg"
+
+func main() {
+    c := &gotenberg.Client{Hostname: "http://localhost:3000"}
+    req := gotenberg.NewURLRequest("https://google.com")
+    req.SetMargins(gotenberg.NoMargins)
+    dest := "result.pdf"
+    c.Store(req, dest)
+}
+
+ +

PHP

+ +
use TheCodingMachine\Gotenberg\Client;
+use TheCodingMachine\Gotenberg\URLRequest;
+
+$client = new Client('http://localhost:3000', new \Http\Adapter\Guzzle6\Client());
+$request = new URLRequest('https://google.com');
+$request->setMargins(Request::NO_MARGINS);
+$dest = "result.pdf";
+$filename = $client->store($request, $dest);
@@ -531,7 +601,7 @@ in the file index.html. This function will convert a given markdown func main() { c := &gotenberg.Client{Hostname: "http://localhost:3000"} - req, _ := gotenberg.NewMarkdownRequest("index.html", []string{"file.md"}) + req, _ := gotenberg.NewMarkdownRequest("index.html", "file.md") dest := "result.pdf" c.Store(req, dest) } @@ -551,8 +621,8 @@ $markdowns = [ DocumentFactory::makeFromPath('file.md', 'file.md'), ]; $request = new MarkdownRequest($index, $markdowns); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); +$dest = "result.pdf"; +$filename = $client->store($request, $dest); @@ -613,7 +683,7 @@ See the scalability section to find how to mitigate t func main() { c := &gotenberg.Client{Hostname: "http://localhost:3000"} - req, _ := gotenberg.NewOfficeRequest([]string{"document.docx", "document2.docx"}) + req, _ := gotenberg.NewOfficeRequest("document.docx", "document2.docx") dest := "result.pdf" c.Store(req, dest) } @@ -633,8 +703,8 @@ $files = [ DocumentFactory::makeFromPath('document2.docx', 'document2.docx'), ]; $request = new OfficeRequest($files); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); +$dest = "result.pdf"; +$filename = $client->store($request, $dest);

Fonts

- -

By default, only ttf-mscorefonts fonts are installed.

- -

If you wish to use more fonts, you will have to create your own image:

- -
FROM thecodingmachine/gotenberg:3
-
-RUN apt-get -y install yourfonts
-
-
@@ -740,7 +797,7 @@ will merge them and return the resulting PDF file.

func main() { c := &gotenberg.Client{Hostname: "http://localhost:3000"} - req, _ := gotenberg.NewMergeRequest([]string{"file.pdf", "file2.pdf"}) + req, _ := gotenberg.NewMergeRequest("file.pdf", "file2.pdf") dest := "result.pdf" c.Store(req, dest) } @@ -760,8 +817,8 @@ $files = [ DocumentFactory::makeFromPath('file2.pdf', 'file2.pdf'), ]; $request = new MergeRequest($files); -$dirPath = "/foo"; -$filename = $client->store($request, $dirPath); +$dest = "result.pdf"; +$filename = $client->store($request, $dest);
@@ -839,7 +896,7 @@ $resp = $client->post($request); # your others services gotenberg: - image: thecodingmachine/gotenberg:3 + image: thecodingmachine/gotenberg:4

You may now launch your services using:

@@ -868,6 +925,21 @@ a simple GET request.

+
+

Fonts

+

By default, a handful of fonts are installed. Asian characters are also supported out of the box.

+ +

If you wish to use more fonts, you will have to create your own image:

+ +
FROM thecodingmachine/gotenberg:4
+
+RUN apt-get -y install yourfonts
+
+ +
+