wrklst/docxmustache

docx template manipulation class, based on mustache templating language

v0.0.37 2024-03-20 14:56 UTC

Requires

• php: >=8.1
• intervention/image: ^2.7
• mustache/mustache: ^2.12
• wrklst/madzipper: ^1.5

MIT

• Tobias Vielmetter-Diekmann

• php
• template
• mustache
• OpenXML
• docx
• laravel

README

DocxMustache for Laravel 11.x

DocxMustache is a Laravel 11.x package for manipulating DOCX templates using the Mustache templating language. It allows you to merge richly styled Word documents with data from various sources. This package is still under active development, and breaking changes may occur.

With DocxMustache, you can:

• Replace text using Mustache syntax.
• Embed images dynamically.
• Support basic HTML styling (bold, italic, underline).

Installation

Install the package via Composer:

composer require wrklst/docxmustache

Refer to the Examples section and the examples folder for configuration and usage instructions.

Features

HTML Conversion

Basic HTML conversion is supported, including:

• Bold (<b>)
• Italic (<i>)
• Underline (<u>)

Limitations:

• Does not support combined styling (e.g., bold + italic).
• Non-HTML values must be escaped using:

htmlspecialchars($value, ENT_COMPAT, 'UTF-8');

Special Note: To prevent unnecessary escaping of HTML, prefix the value with:

*[[DONOTESCAPE]]*

Replacing Images

Dynamic image replacement is supported. Follow these steps:

1. Add the image URL (reachable and supported format) to the image's alt text description field in the DOCX template.
2. Use pseudo-tags around the URL, like so:

[IMG-REPLACE]http://placehold.it/350x150[/IMG-REPLACE]

Note: Images will be resampled to match the constraints of the placeholder image in the template.

DOCX to PDF Conversion

To enable DOCX-to-PDF conversion, install libreoffice-common on your server:

sudo apt install libreoffice-common

For Arial font support, install:

sudo apt-get install ttf-mscorefonts-installer

Dependencies

Required Packages

• mustache/mustache
• intervention/image

For Intervention Image, ensure you:

1. Add the provider and alias to your app config.
2. Install gd or imagick as required (details here).

Laravel-Specific Dependencies

If you want to port the package to a non-Laravel environment, consider replacing:

• Storage and File Classes: Based on Flysystem, can be replaced with PHP native file handling.
• Process Handling: Uses \Symfony\Component\Process\Process for PDF conversion.

Example

Check out the examples folder for sample templates and usage.

Contributions

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a pull request with your changes.
3. Include a corresponding issue for discussion.

We’ll be happy to review and discuss your ideas!

Why Another DOCX Templating Solution?

While there are existing libraries for DOCX manipulation, they often:

• Use proprietary or non-standard templating syntaxes.
• Focus on complex feature sets, making them heavyweight for simple use cases.

DocxMustache was designed to:

• Use the widely adopted Mustache syntax.
• Provide simple and intuitive value and image replacement.
• Support repeating content in multiple dimensions.

Alternatives

Here are other popular PHP libraries for DOCX manipulation:

• openTBS – Tiny But Strong
• PHPWord
• docxtemplater pro (MIT licensed; image replacement requires a commercial plugin)
• docxpresso (commercial)
• phpdocx (commercial)