https://github.com/thecodingmachine/print.service

PDF, docx, html generator service of docx or twig template
https://github.com/thecodingmachine/print.service

Last synced: 9 months ago
JSON representation

PDF, docx, html generator service of docx or twig template

Host: GitHub
URL: https://github.com/thecodingmachine/print.service
Owner: thecodingmachine
Created: 2016-07-13T13:56:02.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2016-12-16T10:05:21.000Z (about 9 years ago)
Last Synced: 2025-04-11T18:59:50.488Z (10 months ago)
Language: PHP
Size: 160 KB
Stars: 8
Watchers: 10
Forks: 5
Open Issues: 2
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# Goals

Simple API for generating documents according to various types of templates (.twig, .docx, .pdf) and a set of data.

# Setting up your environment

## Docker, docker-compose

Install Docker (**>= 1.10**) for MacOSX / Linux following the official instructions:

Install docker-compose (**>= 1.8.0**) for MacOSX / Linux following the official instructions:

Move to the root directory of the project. You'll have to launch the following commands (replace ```env``` by one of: ```dev```, ```preprod```, ```prod```):

## Install php packages using:

```
./bin/composer env install
```

## Build the docker container:

```
./bin/build env
```

## Start the docker container:

```
./bin/up env
```

## Last but not least

Install Mouf framework:

# Candies

## Clean your docker cache:

```
./bin/clean
```

## Stop the container:

```
./bin/stop env
```

# API

## Request headers

Your request must have the following headers:

**Content-Type:** application/json

If you want a HTML output:

**Accept:** text/html

A Word document output:

**Accept:** application/vnd.openxmlformats-officedocument.wordprocessingml.document

A PDF document output:

**Accept:** application/pdf

Also this API works with basic authentication. Please look at [API configuration](#api-configuration)!

## API stack

* twig: (twig to HTML)
* PDFtk: (merging PDF)
* wkhtmltopdf: (HTML to PDF)
* LibreOffice: (Word to PDF conversion with soffice command)
* Node 4_x with the following libraries:
* (for populating a word template)
* (module for populating charts of a word template)
* (module for images of a word template)
* (module for populating links of a word template)

## Example of a JSON for a single document

```json
{
"templates": [
{
"order": 0,
"contentType": "text/html",
"url": "http://adomain.com/yourTemplate.twig",
"headerUrl": "http://adomain.com/yourTemplate.twig",
"footerUrl": "http://adomain.com/yourTemplate.twig"
},
{
"order": 1,
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"url": "http://adomain.com/yourTemplate.docx"
},
{
"order": 2,
"contentType": "application/pdf",
"url": "http://adomain.com/yourTemplate.pdf"
},
],
"data": {
"property1": "value",
"integer": 1,
"decimal": 2.33,
"array1": [
{
"id":1,
"objectProperty": "value"
},
{
"id":2,
"objectProperty": "value"
},
],
"image": {
"type": "image",
"url": "http://adomaine.com/yourimage.png"
},
"link": {
"type": "link",
"text": "yourtextlink",
"url": "http//adomain.com"
}
}
}
```

## How does it work?

1. Parse the request
2. Download the templates (**note:** the API uses a cache to detect if the templates must be downloaded again; when retrieving a template, the cache will check for the Expire header line.)
3. Populate the templates according to the data
4. Merge templates into one final document
5. Serve the final document

## Rules

### Templates properties

* order: required
* contentType: required
* url: required
* headerUrl: _optional_
* footerUrl: _optional_

**Note:** the **headerUrl** and **footerUrl** are only available for twig templates.

### Data properties

The data object is optional. Except for image and link special cases (see below), as long as the JSON is valid the API will be able to populate your templates.

### Populating templates

#### Twig template

Considering this data object:

```json
"data": {
"property1": "value",
"image": {
"type": "image",
"url": "http://adomaine.com/yourimage.png"
},
"link": {
"type": "link",
"text": "yourtextlink",
"url": "http//adomain.com"
}
}
```

Your twig template will be filled using:

```php
"value",
"image" => "http://adomaine.com/yourimage.png",
"link" => [
"text" => "yourtextlink",
"url" => "http//adomain.com"
]
];
?>
```

#### Word template

Considering this data object:

```json
"data": {
"property1": "value",
"image": {
"type": "image",
"url": "http://adomaine.com/yourimage.png"
},
"link": {
"type": "link",
"text": "yourtextlink",
"url": "http//adomain.com"
}
}
```

Your Word template will be filled using:

```json
{
"property1": "value",
"image": "yourimagerealpath.png",
"link": {
"text": "yourtextlink",
"url": "http//adomain.com"
}
}
```

**Note:** as you can see, the image specified in the original JSON has been downloaded by the API, because of a limitation of the docx templater image module which is not able to work with remote files.

### Media type exception

Except for application/pdf, your accept header line must match your templates' content types.

For example :

This request will throw an exception if you are requesting a HTML or a Word document output.

## api/v1/documents/generate (POST)

Allows to generate a single document according to one or more templates and data.

## api/v1/documents/merge (POST)

Allows to generate many documents and merge them into one final document.

```json
[
{
"templates": [
{
"order": 0,
"contentType": "application/pdf",
"url": "http://adomain.com/yourTemplate.pdf"
},
]
},
{
"templates": [
{
"order": 0,
"contentType": "text/html",
"url": "http://adomain.com/yourTemplate.twig",
"headerUrl": "http://adomain.com/yourTemplate.twig",
"footerUrl": "http://adomain.com/yourTemplate.twig"
},
{
"order": 1,
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"url": "http://adomain.com/yourTemplate.docx"
},
{
"order": 2,
"contentType": "application/pdf",
"url": "http://adomain.com/yourTemplate.pdf"
},
],
"data": {
"property1": "value"
}
}
]
```

## API configuration

### Defining user(s) for HTTP basic authentication

Go to and update the options parameter.

# FAQ / Known issues

## The docker container is not running

You might have to stop your local apache.

## I've some permissions issues in Mouf

You might have to stop the container (`./bin/stop`) and start it again (`/bin/up $(pwd)`).

## I can't generate a Word document with many Word templates

Yep, this is currently a limitation. For now, you are only able to generate one Word document with one Word template.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/thecodingmachine/print.service

Awesome Lists containing this project

README