wrklst / docxmustache
docx template manipulation class, based on mustache templating language
Requires
- php: ^8.3
- ext-fileinfo: *
- ext-gd: *
- ext-simplexml: *
- ext-zip: *
- illuminate/filesystem: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
- intervention/image: ^4
- mustache/mustache: ^2.12|^3.0
- symfony/process: ^7.0|^8.0
Requires (Dev)
- orchestra/testbench: ^10.0|^11.0
- phpunit/phpunit: ^11.5|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-master
- v0.1.1
- v0.1.0
- v0.0.53
- v0.0.52
- v0.0.51
- v0.0.50
- v0.0.49
- v0.0.48
- v0.0.47
- v0.0.46
- v0.0.45
- v0.0.44
- v0.0.43
- v0.0.42
- v0.0.41
- v0.0.40
- v0.0.39
- v0.0.38
- v0.0.37
- v0.0.36
- v0.0.35
- v0.0.34
- v0.0.33
- v0.0.32
- v0.0.31
- v0.0.30
- v0.0.29
- v0.0.28
- v0.0.27
- v0.0.26
- v0.0.25
- v0.0.24
- v0.0.23
- v0.0.22
- v0.0.21
- v0.0.20
- v0.0.19
- v0.0.18
- v0.0.17
- v0.0.16
- v0.0.15
- v0.0.14
- v0.0.13
- v0.0.12
- v0.0.11
- v0.0.10
- v0.0.9
- v0.0.8
- v0.0.7
- v0.0.6
- v0.0.5
- v0.0.4
- v0.0.3
- v0.0.2
- v0.0.1
- dev-scrutinizer-patch-4
- dev-scrutinizer-patch-3
- dev-scrutinizer-patch-2
- dev-scrutinizer-patch-1
This package is auto-updated.
Last update: 2026-11-13 20:31:48 UTC
README
DocxMustache for Laravel 12.x and 13.x
Docx template manipulation class for Laravel 12.x and 13.x, based on mustache templating language. This class is still under heavy development and works more like proof of concept at the moment. Things will change quickly and might break things.
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
Usage
use WrkLst\DocxMustache\DocxMustache; // the template is read from <storagePathPrefix><template> on the given (local) disk $docx = new DocxMustache(['items' => $items], 'example_template.docx', storageDisk: 'local', storagePathPrefix: 'app/'); $docx->execute(); // execute(144) stores images with more pixels for high resolution screens $path = $docx->storagePath($docx->local_path.$docx->template_file_name); // the generated docx $pdf = $docx->saveAsPdf(); // optional, needs LibreOffice
Each run writes into its own working directory <storagePathPrefix>DocxMustache/<unique id>/.
Cleanup
Every run first deletes the working directories of earlier runs that are older than 48 hours, including the documents generated in them. Move a result away if you need it longer, or change the lifetime (in hours):
$docx = new DocxMustache($data, 'template.docx', tmpDirLifetime: 2); $docx->tmpDirLifetime = 0.5; // or as a property, before execute() $docx->tmpDirLifetime = null; // never delete anything
See the example folder for a template and a controller.
Features
HTML Conversion
Basic HTML conversion is supported, including:
- Bold (
<b>,<strong>) - Italic (
<i>,<em>) - Underline (
<u>) - Line breaks (
<br>)
Values are escaped by default, so HTML in them shows up as text. To have a value treated as HTML, prefix it with:
*[[DONOTESCAPE]]*
Limitations:
- Tags are lowercase, without attributes, and have to be closed.
- Styles combine only when the tags are nested (
<b>bold <i>and italic</i></b>). - Everything else in such a value has to be valid XML: escape text with
htmlspecialchars($value, ENT_COMPAT, 'UTF-8').
Replacing Images
Dynamic image replacement is supported. Follow these steps:
- Add the image source (supported format) to the image's alt text description field in the DOCX template.
- Use pseudo-tags around it. The path must be absolute and inside
storage_path():
[LOCAL_IMG_REPLACE]/var/www/app/storage/app/logo.png[/LOCAL_IMG_REPLACE]
Images can also be fetched over HTTP by putting a URL of your own inside [IMG-REPLACE] / [/IMG-REPLACE] instead.
Notes:
- Images will be resampled to match the constraints of the placeholder image in the template and stored as JPEG. GIF, JPEG, PNG and BMP sources are supported.
- If an image cannot be loaded, the placeholder image stays.
- Pictures are replaced in the main document, headers, footers, footnotes and endnotes.
- The picture has to be stored the way current Word versions do (DrawingML). Pictures in documents converted from the old
.docformat (VML) are ignored: insert the picture again in a.docx.
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
Requirements
- PHP 8.3 or newer (required by intervention/image 4)
- Laravel 12.x or 13.x (
illuminate/support) - The
zip,gd,simplexmlandfileinfoPHP extensions
Required Packages
- mustache/mustache 2.x or 3.x
- intervention/image 4.x, used with its GD driver. No provider or alias is needed.
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\Processfor PDF conversion.
Example
Check out the example folder for a sample template and controller.
Testing
composer install
composer test
Contributions
Contributions are welcome! To contribute:
- Fork the repository.
- Create a pull request with your changes.
- 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)

