{"id":18929700,"url":"https://github.com/thecodingmachine/print.service","last_synced_at":"2025-04-15T15:31:09.316Z","repository":{"id":66284959,"uuid":"63250464","full_name":"thecodingmachine/print.service","owner":"thecodingmachine","description":"PDF, docx, html generator service of docx or twig template","archived":false,"fork":false,"pushed_at":"2016-12-16T10:05:21.000Z","size":164,"stargazers_count":8,"open_issues_count":2,"forks_count":5,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-11T18:59:50.488Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thecodingmachine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-13T13:56:02.000Z","updated_at":"2023-07-07T18:10:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"d83bc916-3a7f-453b-8d0c-7f1dc9f99e47","html_url":"https://github.com/thecodingmachine/print.service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fprint.service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fprint.service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fprint.service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thecodingmachine%2Fprint.service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thecodingmachine","download_url":"https://codeload.github.com/thecodingmachine/print.service/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249097878,"owners_count":21212366,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T11:34:34.544Z","updated_at":"2025-04-15T15:31:09.310Z","avatar_url":"https://github.com/thecodingmachine.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Goals\n\nSimple API for generating documents according to various types of templates (.twig, .docx, .pdf) and a set of data.\n\n# Setting up your environment\n\n## Docker, docker-compose\n\nInstall Docker (**\u003e= 1.10**) for MacOSX / Linux following the official instructions: \u003chttps://docs.docker.com/engine/installation/\u003e\n\nInstall docker-compose (**\u003e= 1.8.0**) for MacOSX / Linux following the official instructions: \u003chttps://docs.docker.com/compose/install/\u003e\n\nMove to the root directory of the project. You'll have to launch the following commands (replace ```env``` by one of: ```dev```, ```preprod```, ```prod```):\n\n## Install php packages using:\n\n```\n./bin/composer env install\n```\n\n## Build the docker container:\n\n```\n./bin/build env\n```\n\n## Start the docker container:\n\n```\n./bin/up env\n```\n\n## Last but not least\n\nInstall Mouf framework: \u003chttp://localhost/vendor/mouf/mouf\u003e\n\n# Candies\n\n## Clean your docker cache:\n\n```\n./bin/clean\n```\n\n## Stop the container:\n\n```\n./bin/stop env\n```\n\n# API\n\n## Request headers\n\nYour request must have the following headers:\n\n**Content-Type:** application/json\n\nIf you want a HTML output:\n\n**Accept:** text/html\n\nA Word document output:\n\n**Accept:** application/vnd.openxmlformats-officedocument.wordprocessingml.document\n\nA PDF document output:\n\n**Accept:** application/pdf\n\nAlso this API works with basic authentication. Please look at [API configuration](#api-configuration)!\n\n## API stack\n\n* twig: \u003chttp://twig.sensiolabs.org/\u003e (twig to HTML)\n* PDFtk: \u003chttps://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/\u003e (merging PDF)\n* wkhtmltopdf: \u003chttp://wkhtmltopdf.org/\u003e (HTML to PDF)\n* LibreOffice: \u003chttps://www.libreoffice.org/download/libreoffice-fresh/\u003e (Word to PDF conversion with soffice command)\n* Node 4_x with the following libraries:\n    * \u003chttps://github.com/open-xml-templating/docxtemplater\u003e (for populating a word template)\n    * \u003chttps://github.com/prog666/docxtemplater-chart-module\u003e (module for populating charts of a word template)\n    * \u003chttps://github.com/open-xml-templating/docxtemplater-image-module\u003e (module for images of a word template)\n    * \u003chttps://github.com/sujith3g/docxtemplater-link-module\u003e (module for populating links of a word template)\n\n## Example of a JSON for a single document\n\n```json\n{\n    \"templates\": [\n        {\n            \"order\": 0,\n            \"contentType\": \"text/html\",\n            \"url\": \"http://adomain.com/yourTemplate.twig\",\n            \"headerUrl\": \"http://adomain.com/yourTemplate.twig\",\n            \"footerUrl\": \"http://adomain.com/yourTemplate.twig\"\n        },\n        {\n            \"order\": 1,\n            \"contentType\": \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n            \"url\": \"http://adomain.com/yourTemplate.docx\"\n        },\n        {\n            \"order\": 2,\n            \"contentType\": \"application/pdf\",\n            \"url\": \"http://adomain.com/yourTemplate.pdf\"\n        },\n    ],\n    \"data\": {\n        \"property1\": \"value\",\n        \"integer\": 1,\n        \"decimal\": 2.33,\n        \"array1\": [\n            {\n                \"id\":1,\n                \"objectProperty\": \"value\"\n            },\n            {\n                \"id\":2,\n                \"objectProperty\": \"value\"\n            },\n        ],\n        \"image\": {\n            \"type\": \"image\",\n            \"url\": \"http://adomaine.com/yourimage.png\"\n        },\n        \"link\": {\n            \"type\": \"link\",\n            \"text\": \"yourtextlink\",\n            \"url\": \"http//adomain.com\"\n        }\n    }\n}\n```\n\n## How does it work?\n\n1. Parse the request\n2. 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.)\n3. Populate the templates according to the data\n4. Merge templates into one final document\n5. Serve the final document\n\n## Rules\n\n### Templates properties\n\n* order: required\n* contentType: required\n* url: required\n* headerUrl: _optional_\n* footerUrl: _optional_\n\n**Note:** the **headerUrl** and **footerUrl** are only available for twig templates.\n\n### Data properties\n\nThe 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.\n\n### Populating templates\n\n#### Twig template\n\nConsidering this data object:\n\n```json\n\"data\": {\n    \"property1\": \"value\",\n    \"image\": {\n        \"type\": \"image\",\n        \"url\": \"http://adomaine.com/yourimage.png\"\n    },\n    \"link\": {\n        \"type\": \"link\",\n        \"text\": \"yourtextlink\",\n        \"url\": \"http//adomain.com\"\n    }\n}\n```\n\nYour twig template will be filled using:\n\n```php\n\u003c?php\n[\n    \"property1\" =\u003e \"value\",\n    \"image\" =\u003e \"http://adomaine.com/yourimage.png\",\n    \"link\" =\u003e [\n        \"text\" =\u003e \"yourtextlink\",\n        \"url\" =\u003e \"http//adomain.com\"\n    ]\n];\n?\u003e\n```\n\n#### Word template\n\nConsidering this data object:\n\n```json\n\"data\": {\n    \"property1\": \"value\",\n    \"image\": {\n        \"type\": \"image\",\n        \"url\": \"http://adomaine.com/yourimage.png\"\n    },\n    \"link\": {\n        \"type\": \"link\",\n        \"text\": \"yourtextlink\",\n        \"url\": \"http//adomain.com\"\n    }\n}\n```\n\nYour Word template will be filled using:\n\n```json\n{\n    \"property1\": \"value\",\n    \"image\": \"yourimagerealpath.png\",\n    \"link\": {\n        \"text\": \"yourtextlink\",\n        \"url\": \"http//adomain.com\"\n    }\n}\n```\n\n**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.\n\n### Media type exception\n\nExcept for application/pdf, your accept header line must match your templates' content types.\n\nFor example :\n\n```json\n{\n    \"templates\": [\n        {\n            \"order\": 0,\n            \"contentType\": \"text/html\",\n            \"url\": \"http://adomain.com/yourTemplate.twig\",\n            \"headerUrl\": \"http://adomain.com/yourTemplate.twig\",\n            \"footerUrl\": \"http://adomain.com/yourTemplate.twig\"\n        },\n        {\n            \"order\": 1,\n            \"contentType\": \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n            \"url\": \"http://adomain.com/yourTemplate.docx\"\n        },\n        {\n            \"order\": 2,\n            \"contentType\": \"application/pdf\",\n            \"url\": \"http://adomain.com/yourTemplate.pdf\"\n        },\n    ],\n    \"data\": {\n        \"property1\": \"value\"\n    }\n}\n```\n\nThis request will throw an exception if you are requesting a HTML or a Word document output.\n\n## api/v1/documents/generate (POST)\n\nAllows to generate a single document according to one or more templates and data.\n\n## api/v1/documents/merge (POST)\n\nAllows to generate many documents and merge them into one final document.\n\n```json\n[\n    {\n        \"templates\": [\n            {\n                \"order\": 0,\n                \"contentType\": \"application/pdf\",\n                \"url\": \"http://adomain.com/yourTemplate.pdf\"\n            },\n        ]\n    },\n    {\n        \"templates\": [\n            {\n                \"order\": 0,\n                \"contentType\": \"text/html\",\n                \"url\": \"http://adomain.com/yourTemplate.twig\",\n                \"headerUrl\": \"http://adomain.com/yourTemplate.twig\",\n                \"footerUrl\": \"http://adomain.com/yourTemplate.twig\"\n            },\n            {\n                \"order\": 1,\n                \"contentType\": \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n                \"url\": \"http://adomain.com/yourTemplate.docx\"\n            },\n            {\n                \"order\": 2,\n                \"contentType\": \"application/pdf\",\n                \"url\": \"http://adomain.com/yourTemplate.pdf\"\n            },\n        ],\n        \"data\": {\n            \"property1\": \"value\"\n        }\n    }\n]\n```\n\n## API configuration\n\n### Defining user(s) for HTTP basic authentication\n\nGo to \u003chttp://localhost/vendor/mouf/mouf/ajaxinstance/?name=httpBasicAuthenticationMiddleware\u003e and update the options parameter.\n\n# FAQ / Known issues\n\n## The docker container is not running\n\nYou might have to stop your local apache.\n\n## I've some permissions issues in Mouf\n\nYou might have to stop the container (`./bin/stop`) and start it again (`/bin/up $(pwd)`).\n\n## I can't generate a Word document with many Word templates\n\nYep, this is currently a limitation. For now, you are only able to generate one Word document with one Word template.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodingmachine%2Fprint.service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthecodingmachine%2Fprint.service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthecodingmachine%2Fprint.service/lists"}