Compiled mode: Linux, Windows and macOS executables to work with DOCX templates and get the maximum performance

Supported OS

Compiled mode includes executables for the following operating systems and architectures:

Linux 64-bit
Linux ARM64
Windows 64-bit
macOS 64-bit

Using the Compiled mode

Compiled mode can be used by calling the executable standalone using CLI or a PHP wrapper that calls the executable. phpdocx includes the CompiledMode class to call Compiled mode from PHP.

In order to work with the Compiled mode from CLI, it is enough to execute the available command in the compiled-mode directory for the corresponding OS. E.g., this shows how to replace placeholders of a template with the data.json information:

phpdocx --data data.json --template template.docx

Or, in its short version:

phpdocx -d data.json -t template.docx

You can invoke the Compiled mode with PHP instead of CLI, just using the CompiledMode class. For example:

require_once 'classes/CompiledMode.php';

// set the path to the executable file of the OS. Linux 64-bit as sample
$execPath = 'compiled-mode/bin/linux/64-bit/phpdocx';

$exec = new CompiledMode($execPath);
// JSON data
$data = '{"template":{"replace_texts":[{"placeholders":["VAR_1","VAR_2","VAR_HEADER_1","VAR_COMMENT_1","VAR_FOOTER_1","VAR_ENDNOTE_1","VAR_FOOTNOTE_1"],"values":["New value 1","New value 2","New header value 1","New comment value 1","New footer value 1","New endnote value 1","New footnote value 1"]}]}}';
$output = $exec->replacePlaceholders('template.docx', $data, 'output.docx');

It is also possible to call the executable directly with PHP functions like exec or system.

The "-h" parameter shows the complete help of the command:

phpdocx -h

USAGE:
    phpdocx [OPTIONS] --template <template>

OPTIONS:
    -a, --action <action>        Action. [possible values: default, get_styles, get_variables]
    -d, --data <data>            JSON data.
    -h, --help                   Print help information
    -o, --output <output>        Output file.
    -t, --template <template>    Template file.
    -v                           Level of verbosity.
    -V, --version                Print version information

The available actions are the following: default (replace and remove placeholders), get_styles and get_variables.

JSON structures

The default action replaces placeholders with a JSON content. This JSON can be generated from PHP or any other coding language, even as plain text.

The following examples illustrate the structure of the JSON that replaces the existing placeholders.

Remove placeholders:

{
    "template": {
        "remove_placeholders": true
    }
}

Replace text placeholders:

{
    "template": {
        "replace_texts": [
            {
                "placeholders": [
                ],
                "values": [
                ]
            }
        ]
    }
}

Replace list placeholders:

{
    "template": {
        "replace_lists": [
            {
                "placeholders": [
                ],
                "values": [
                ]
            }
        ]
    }
}

Replace table placeholders:

{
    "template": {
        "replace_tables": [
            {
                "placeholders": [
                ],
                "values": [
                ]
            }
        ]
    }
}

Replace checkbox placeholders:

{
    "template": {
        "replace_checkboxes": [
            {
                "placeholders": [
                ],
                "values": [
                ]
            }
        ]
    }
}

In the JSON content there is also an "options" feature, with an additional set of options:

content_type: document, comments, endnotes, footers, footnotes, headers. All as default.
max_replacements: limit the number of replacements.

Examples

JSON for replacing text and table placeholders:

{
    "template": {
        "replace_texts": [
            {
                "placeholders": [
                    "VAR_1",
                    "VAR_2",
                    "VAR_HEADER_1",
                    "VAR_COMMENT_1",
                    "VAR_FOOTER_1",
                    "VAR_ENDNOTE_1",
                    "VAR_FOOTNOTE_1"
                ],
                "values": [
                    "New value 1",
                    "New value 2",
                    "New header value 1",
                    "New comment value 1",
                    "New footer value 1",
                    "New endnote value 1",
                    "New footnote value 1"
                ]
            }
        ],
        "replace_tables": [
            {
                "placeholders": [
                    [
                        "NAME",
                        "STREET",
                        "PHONE"
                    ],
                    [
                        "INFO1",
                        "INFO2"
                    ]
                ],
                "values": [
                    [
                        [
                            "John",
                            "Mary",
                            "Tom",
                            "Andy"
                        ],
                        [
                            "Street 1,2B",
                            "Avenue 89",
                            "Street 6T",
                            "Avenue 12"
                        ],
                        [
                            "+00 1002",
                            "03 2112",
                            "+00 122 1002",
                            "+00 122 1003"
                        ]
                    ],
                    [
                        [
                            "Info A",
                            "Info B"
                        ],
                        [
                            "Description A",
                            "Description B"
                        ]
                    ]
                ]
            }
        ]
    }
}

JSON for replacing text placeholders on headers and footers only:

{
    "template": {
        "replace_texts": [
            {
                "placeholders": [
                    "VAR_1",
                    "VAR_HEADER_1"
                ],
                "values": [
                    "New value 1",
                    "New header value 1"
                ],
                "options": {
                    "content_type": "headers"
                }
            },
            {
                "placeholders": [
                    "VAR_FOOTER_1"
                ],
                "values": [
                    "New footer value 1"
                ],
                "options": {
                    "content_type": "footers"
                }
            }
        ]
    }
}

JSON for replacing just the first occurrence of a placeholder:

{
    "template": {
        "replace_tables": [
            {
                "placeholders": [
                    [
                        "NAME",
                        "STREET",
                        "PHONE"
                    ]
                ],
                "values": [
                    [
                        [
                            "John",
                            "Mary",
                            "Tom",
                            "Andy"
                        ],
                        [
                            "Street 1,2B",
                            "Avenue 89",
                            "Street 6T",
                            "Avenue 12"
                        ],
                        [
                            "+00 1002",
                            "03 2112",
                            "+00 122 1002",
                            "+00 122 1003"
                        ]
                    ]
                ],
                "options": {
                    "max_replacements": 1
                }
            },
            {
                "placeholders": [
                    [
                        "NAME",
                        "STREET",
                        "PHONE"
                    ]
                ],
                "values": [
                    [
                        [
                            "Snow",
                            "Jack",
                            "Frau",
                            "Wolf"
                        ],
                        [
                            "No address",
                            "Avenue 89",
                            "Street 6T",
                            "Avenue 12"
                        ],
                        [
                            "+01",
                            "+03",
                            "+098",
                            "+45"
                        ]
                    ]
                ],
                "options": {
                    "max_replacements": 1
                }
            }
        ]
    }
}

Tips

The placeholders to be replaced must be wrapped using ${ } in the DOCX template.
In order to call the executable in Windows from PHP it is advisable to indicate the absolute path.
The compiled-mode directory has the executables of the Compiled mode (bin folder) and use cases in CLI and PHP for every functionality (samples folder).